# Module cloudi_service_queue

- Description
- Data Types
- Function Index
- Function Details

### CloudI Persistent Queue Service

Use Write Ahead Logging (WAL) to persist service requests. This service provides a leaner alternative to persistent messaging queues (e.g., when compared to RabbitMQ, both topics/queues). The filesystem is used for keeping the queue service requests persistent and the queue file path is provided to this service's configuration arguments. You must make sure the queue file path is unique. If you use a process count higher than 1, make sure to have "${I}" within the file path, so the process index is used within the file path.

.

Copyright © 2014-2019 Michael Truog

Version: 1.8.0 May 27 2021 01:43:08 ------------------------------------------------------------------------

Behaviours: `cloudi_service`.

Authors: Michael Truog (`mjtruog at protonmail dot com`).

## Description

### CloudI Persistent Queue Service

Use Write Ahead Logging (WAL) to persist service requests. This service provides a leaner alternative to persistent messaging queues (e.g., when compared to RabbitMQ, both topics/queues). The filesystem is used for keeping the queue service requests persistent and the queue file path is provided to this service's configuration arguments. You must make sure the queue file path is unique. If you use a process count higher than 1, make sure to have "${I}" within the file path, so the process index is used within the file path.

The fault_isolation service argument determines the fault-tolerance guarantee for the request/response exchange. When fault_isolation is set to 'destination' (the default), the sender is isolated from destination instability only. So, this means persistence to the filesystem begins and ends within this service and the source could fail to receive the response due to its own instability.

When fault_isolation is set to 'both', both the sender and the destination are isolated from instability. Persistence of the request begins when this service receives the incoming service request, but persistence ends after the source receives a service request that contains the response. So, 'both' does not assume the source Erlang pid remains alive during the request/response exchange. If you need requests to survive an Erlang VM restart, this is the mode you should use. (This assumes the source is also meant to receive the response, which doesn't need to be the case with 'both'. Only a valid service name needs to be specified for the destination of the response (with a <<"service_name">> key/value entry in the RequestInfo of the initial service request) and it doesn't need to be the source of the request).

The retry service argument controls the number of retries during the lifetime of this service's instance. So, this means that after an Erlang VM restart, the retry counter will start from 0 after the initial retry that occurs when the WAL is read upon startup.

The amount of time the service request is persisted is always limited by the timeout of the service request. Tracking the time taken by a service request depends on the Erlang VM time-keeping being dependable which depends on the OS time-keeping not varying wildly, if fault_isolation is set to 'both' and an Erlang VM restart causes an old queue file to be used (the new Erlang VM OS process will use the new OS time to determine if service requests in the old queue file have timed-out based on each service request timeout value). If the fault_isolation service argument is set to 'both', the original service request timeout value will be used for the service request send to the destination and the service request send containing the response.

If the retry service argument is set higher than 0, any retry attempts will occur during the time period defined by the timeout of the service request (i.e., a service request is only retried if its timeout has not expired). Any usage of the retry_delay service argument will contribute to time elapsed during the time period defined by the timeout of the service request.

To make sure cloudi_service_queue gets a service request timeout quickly (i.e., without depending on the timeout elapsing locally, despite the timeout being a small value), it is common to set the service configuration options request_timeout_immediate_max and response_timeout_immediate_max to 'limit_min'. If the retry_delay service argument is used, setting the request_name_lookup service configuration option to async is best if the service request destinations are expected to rarely be present (i.e., only appear when anticipating the receive of data).

## Data Types

### request()

`request() = request_destination_mode() | request_both_mode()`

### request_both_mode()

`request_both_mode() = #both_request{name = cloudi_service:service_name(), request_info = cloudi_service:request_info(), request = cloudi_service:request(), timeout = cloudi_service:timeout_value_milliseconds(), priority = cloudi_service:priority(), trans_id = cloudi_service:trans_id(), next_name = cloudi_service:service_name(), next_trans_id = cloudi_service:trans_id()} | #both_response{name = cloudi_service:service_name(), response_info = cloudi_service:response_info(), response = cloudi_service:response(), timeout = cloudi_service:timeout_value_milliseconds(), priority = cloudi_service:priority(), trans_id = cloudi_service:trans_id()}`

cloudi_write_ahead_logging

### request_destination_mode()

`request_destination_mode() = #destination_request{request_type = cloudi_service:request_type(), name = cloudi_service:service_name(), pattern = cloudi_service:service_name_pattern(), request_info = cloudi_service:request_info(), request = cloudi_service:request(), timeout = cloudi_service:timeout_value_milliseconds(), priority = cloudi_service:priority(), trans_id = cloudi_service:trans_id(), pid = cloudi_service:source()}`

fault_isolation: both

## Function Index

cloudi_service_handle_info/3 |
cloudi_service_handle_request/11 |
cloudi_service_init/4 |
cloudi_service_terminate/3 |

## Function Details

### cloudi_service_handle_info/3

`cloudi_service_handle_info(Return_async_active, State, Dispatcher) -> any()`

### cloudi_service_handle_request/11

`cloudi_service_handle_request(RequestType, Name, Pattern, RequestInfo, Request, Timeout, Priority, TransId, Pid, State, Dispatcher) -> any()`

### cloudi_service_init/4

`cloudi_service_init(Args, Prefix, Timeout, Dispatcher) -> any()`

### cloudi_service_terminate/3

`cloudi_service_terminate(Reason, Timeout, State) -> any()`

Generated by EDoc