Current section
Files
Jump to
Current section
Files
doc/cloudi_service_queue.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Module cloudi_service_queue</title>
<link rel="stylesheet" type="text/css" href="stylesheet.css" title="EDoc">
</head>
<body bgcolor="white">
<div class="navbar"><a name="#navbar_top"></a><table width="100%" border="0" cellspacing="0" cellpadding="2" summary="navigation bar"><tr><td><a href="overview-summary.html" target="overviewFrame">Overview</a></td><td><a href="http://www.erlang.org/"><img src="erlang.png" align="right" border="0" alt="erlang logo"></a></td></tr></table></div>
<hr>
<h1>Module cloudi_service_queue</h1>
<ul class="index"><li><a href="#description">Description</a></li><li><a href="#types">Data Types</a></li><li><a href="#index">Function Index</a></li><li><a href="#functions">Function Details</a></li></ul>
<h3><a name="CloudI_Persistent_Queue_Service">CloudI Persistent Queue Service</a></h3><p>
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.</p>.
<p>Copyright © 2014-2019 Michael Truog</p>
<p><b>Version:</b> 1.8.0 Nov 26 2020 19:35:46
------------------------------------------------------------------------</p>
<p><b>Behaviours:</b> <a href="deps/cloudi_core/doc/cloudi_service.html"><tt>cloudi_service</tt></a>.</p>
<p><b>Authors:</b> Michael Truog (<a href="mailto:mjtruog at protonmail dot com"><tt>mjtruog at protonmail dot com</tt></a>).</p>
<h2><a name="description">Description</a></h2>
<h3><a name="CloudI_Persistent_Queue_Service">CloudI Persistent Queue Service</a></h3><p>
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.</p>
<p>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.</p>
<p>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).</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
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).
<h2><a name="types">Data Types</a></h2>
<h3 class="typedecl"><a name="type-request">request()</a></h3>
<p><tt>request() = <a href="#type-request_destination_mode">request_destination_mode()</a> | <a href="#type-request_both_mode">request_both_mode()</a></tt></p>
<h3 class="typedecl"><a name="type-request_both_mode">request_both_mode()</a></h3>
<p><tt>request_both_mode() = #both_request{name = <a href="deps/cloudi_core/doc/cloudi_service.html#type-service_name">cloudi_service:service_name()</a>, request_info = <a href="deps/cloudi_core/doc/cloudi_service.html#type-request_info">cloudi_service:request_info()</a>, request = <a href="deps/cloudi_core/doc/cloudi_service.html#type-request">cloudi_service:request()</a>, timeout = <a href="deps/cloudi_core/doc/cloudi_service.html#type-timeout_value_milliseconds">cloudi_service:timeout_value_milliseconds()</a>, priority = <a href="deps/cloudi_core/doc/cloudi_service.html#type-priority">cloudi_service:priority()</a>, trans_id = <a href="deps/cloudi_core/doc/cloudi_service.html#type-trans_id">cloudi_service:trans_id()</a>, next_name = <a href="deps/cloudi_core/doc/cloudi_service.html#type-service_name">cloudi_service:service_name()</a>, next_trans_id = <a href="deps/cloudi_core/doc/cloudi_service.html#type-trans_id">cloudi_service:trans_id()</a>} | #both_response{name = <a href="deps/cloudi_core/doc/cloudi_service.html#type-service_name">cloudi_service:service_name()</a>, response_info = <a href="deps/cloudi_core/doc/cloudi_service.html#type-response_info">cloudi_service:response_info()</a>, response = <a href="deps/cloudi_core/doc/cloudi_service.html#type-response">cloudi_service:response()</a>, timeout = <a href="deps/cloudi_core/doc/cloudi_service.html#type-timeout_value_milliseconds">cloudi_service:timeout_value_milliseconds()</a>, priority = <a href="deps/cloudi_core/doc/cloudi_service.html#type-priority">cloudi_service:priority()</a>, trans_id = <a href="deps/cloudi_core/doc/cloudi_service.html#type-trans_id">cloudi_service:trans_id()</a>}</tt></p>
<p> cloudi_write_ahead_logging</p>
<h3 class="typedecl"><a name="type-request_destination_mode">request_destination_mode()</a></h3>
<p><tt>request_destination_mode() = #destination_request{request_type = <a href="deps/cloudi_core/doc/cloudi_service.html#type-request_type">cloudi_service:request_type()</a>, name = <a href="deps/cloudi_core/doc/cloudi_service.html#type-service_name">cloudi_service:service_name()</a>, pattern = <a href="deps/cloudi_core/doc/cloudi_service.html#type-service_name_pattern">cloudi_service:service_name_pattern()</a>, request_info = <a href="deps/cloudi_core/doc/cloudi_service.html#type-request_info">cloudi_service:request_info()</a>, request = <a href="deps/cloudi_core/doc/cloudi_service.html#type-request">cloudi_service:request()</a>, timeout = <a href="deps/cloudi_core/doc/cloudi_service.html#type-timeout_value_milliseconds">cloudi_service:timeout_value_milliseconds()</a>, priority = <a href="deps/cloudi_core/doc/cloudi_service.html#type-priority">cloudi_service:priority()</a>, trans_id = <a href="deps/cloudi_core/doc/cloudi_service.html#type-trans_id">cloudi_service:trans_id()</a>, pid = <a href="deps/cloudi_core/doc/cloudi_service.html#type-source">cloudi_service:source()</a>}</tt></p>
<p> fault_isolation: both</p>
<h2><a name="index">Function Index</a></h2>
<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#cloudi_service_handle_info-3">cloudi_service_handle_info/3</a></td><td></td></tr>
<tr><td valign="top"><a href="#cloudi_service_handle_request-11">cloudi_service_handle_request/11</a></td><td></td></tr>
<tr><td valign="top"><a href="#cloudi_service_init-4">cloudi_service_init/4</a></td><td></td></tr>
<tr><td valign="top"><a href="#cloudi_service_terminate-3">cloudi_service_terminate/3</a></td><td></td></tr>
</table>
<h2><a name="functions">Function Details</a></h2>
<h3 class="function"><a name="cloudi_service_handle_info-3">cloudi_service_handle_info/3</a></h3>
<div class="spec">
<p><tt>cloudi_service_handle_info(Return_async_active, State, Dispatcher) -> any()</tt></p>
</div>
<h3 class="function"><a name="cloudi_service_handle_request-11">cloudi_service_handle_request/11</a></h3>
<div class="spec">
<p><tt>cloudi_service_handle_request(RequestType, Name, Pattern, RequestInfo, Request, Timeout, Priority, TransId, Pid, State, Dispatcher) -> any()</tt></p>
</div>
<h3 class="function"><a name="cloudi_service_init-4">cloudi_service_init/4</a></h3>
<div class="spec">
<p><tt>cloudi_service_init(Args, Prefix, Timeout, Dispatcher) -> any()</tt></p>
</div>
<h3 class="function"><a name="cloudi_service_terminate-3">cloudi_service_terminate/3</a></h3>
<div class="spec">
<p><tt>cloudi_service_terminate(Reason, Timeout, State) -> any()</tt></p>
</div>
<hr>
<div class="navbar"><a name="#navbar_bottom"></a><table width="100%" border="0" cellspacing="0" cellpadding="2" summary="navigation bar"><tr><td><a href="overview-summary.html" target="overviewFrame">Overview</a></td><td><a href="http://www.erlang.org/"><img src="erlang.png" align="right" border="0" alt="erlang logo"></a></td></tr></table></div>
<p><i>Generated by EDoc</i></p>
</body>
</html>