# Module cloudi_service

- Description
- Data Types
- Function Index
- Function Details

### CloudI Internal Service Behavior

The interface which all internal services must implement.

Copyright © 2011-2020 Michael Truog

Version: 2.0.1 Dec 3 2021 17:15:35 ------------------------------------------------------------------------

This module defines the `cloudi_service` behaviour.
Required callback functions: `cloudi_service_init/4`, `cloudi_service_terminate/3`.
Optional callback functions: `cloudi_service_handle_request/11`, `cloudi_service_handle_info/3`.

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

## Description

### CloudI Internal Service Behavior

The interface which all internal services must implement.

       The user module should export:

         cloudi_service_init(Args, Prefix, Timeout, Dispatcher)
          ==> {ok, State}
              {stop, Reason}
              {stop, Reason, State}
                     State = undefined, if not returned
                     Reason = restart | shutdown | Term, terminate(State) is called

         cloudi_service_handle_request(RequestType, Name, Pattern,
                                       RequestInfo, Request, Timeout, Priority,
                                       TransId, Pid, State, Dispatcher)
          ==> {reply, Response, NewState}
              {reply, ResponseInfo, Response, NewState}
              {forward, NextName, NextRequestInfo, NextRequest, NewState}
              {forward, NextName, NextRequestInfo, NextRequest,
               NextTimeout, NextPriority, NewState}
              {noreply, NewState}
              {stop, Reason, NewState}
                     Reason = restart | shutdown | Term, terminate(State) is called

         cloudi_service_handle_info(Request, State, Dispatcher)

          ==> {noreply, State}
              {stop, Reason, NewState}
                     Reason = restart | shutdown | Term, terminate(State) is called

         cloudi_service_terminate(Reason, Timeout,
                                  State) Let the user module clean up
              always called when the service terminates

          ==> ok

       The work flow (of the service) can be described as follows:

          User module                                          Generic
          -----------                                          -------
          cloudi_service_init              <-----              .

                                                               loop
          cloudi_service_handle_request    <-----              .
                                           ----->              reply

          cloudi_service_handle_info       <-----              .

          cloudi_service_terminate         <-----              .

## Data Types

### dispatcher()

`dispatcher() = pid()`

### error_reason()

`error_reason() = timeout`

### key_values()

`key_values() = cloudi_key_value:key_values()`

### key_values()

`key_values(Key, Value) = cloudi_key_value:key_values(Key, Value)`

### pattern_pid()

`pattern_pid() = cloudi:pattern_pid()`

### priority()

`priority() = cloudi:priority()`

### priority_value()

`priority_value() = cloudi:priority_value()`

### request()

`request() = cloudi:request()`

### request_info()

`request_info() = cloudi:request_info()`

### request_result()

`request_result() = {reply, ResponseInfo::response_info(), Response::response()} | {forward, NextName::service_name(), NextRequestInfo::request_info(), NextRequest::request(), NextTimeout::timeout_value_milliseconds(), NextPriority::priority_value()} | noreply`

### request_type()

`request_type() = send_async | send_sync`

### response()

`response() = cloudi:response()`

### response_info()

`response_info() = cloudi:response_info()`

### service_name()

`service_name() = cloudi:service_name()`

### service_name_pattern()

`service_name_pattern() = cloudi:service_name_pattern()`

### service_name_pattern_suffix()

`service_name_pattern_suffix() = cloudi:service_name_pattern_suffix()`

### source()

`source() = pid()`

### timeout_milliseconds()

`timeout_milliseconds() = cloudi:timeout_milliseconds()`

### timeout_value_milliseconds()

`timeout_value_milliseconds() = cloudi:timeout_value_milliseconds()`

### trans_id()

`trans_id() = cloudi:trans_id()`

version 1 UUID

## Function Index

context_options/1 | #### Get the context options from the service's configuration. A service would only use this when delaying the creation of a context for child processes.
demonitor/2 | #### Demonitor an Erlang pid. The function will make sure an Erlang pid is demonitored properly.
demonitor/3 | #### Demonitor an Erlang pid with options. The function will make sure an Erlang pid is demonitored properly.
destination_refresh_immediate/1 | #### Configured service destination refresh is immediate. .
destination_refresh_lazy/1 | #### Configured service destination refresh is lazy. .
dispatcher/1 | #### Return the Erlang pid representing the service sender. Use when the Dispatcher is stored and used after the current cloudi_service callback has returned.
duo_mode/1 | #### Determine if duo_mode is enabled. .
forward/9 | #### Forward a service request. .
forward_async/8 | #### Forward an asynchronous service request. .
forward_sync/8 | #### Forward a synchronous service request. .
get_pid/2 | #### Get a service destination based on a service name. .
get_pid/3 | #### Get a service destination based on a service name. .
get_pids/2 | #### Get all service destinations based on a service name. .
get_pids/3 | #### Get a service destination based on a service name. .
mcast_async/3 | #### Send a multicast asynchronous service request. Asynchronous service requests are sent to all services that have subscribed to the service name pattern that matches the destination.
mcast_async/4 | #### Send a multicast asynchronous service request. Asynchronous service requests are sent to all services that have subscribed to the service name pattern that matches the destination.
mcast_async/6 | #### Send a multicast asynchronous service request. Asynchronous service requests are sent to all services that have subscribed to the service name pattern that matches the destination.
mcast_async_active/3 | #### Send a multicast asynchronous service request. Asynchronous service requests are sent to all services that have subscribed to the service name pattern that matches the destination.
mcast_async_active/4 | #### Send a multicast asynchronous service request. Asynchronous service requests are sent to all services that have subscribed to the service name pattern that matches the destination.
mcast_async_active/6 | #### Send a multicast asynchronous service request. Asynchronous service requests are sent to all services that have subscribed to the service name pattern that matches the destination.
mcast_async_passive/3 | #### Send a multicast asynchronous service request. An alias for mcast_async.
mcast_async_passive/4 | #### Send a multicast asynchronous service request. An alias for mcast_async.
mcast_async_passive/6 | #### Send a multicast asynchronous service request. An alias for mcast_async.
monitor/2 | #### Monitor an Erlang pid. The function will make sure an Erlang pid is monitored properly so the cloudi_service_handle_info/3 callback receives the monitor result.
prefix/1 | #### Configured service default prefix. All subscribed/unsubscribed service names use this prefix.
priority_default/1 | #### Configured service default priority. .
process_count/1 | #### Return the initial process count of this instance of the service. The configuration of the service defined how many instances should exist.
process_count_max/1 | #### Return the process count maximum of this instance of the service. This will be the same as the process_count, unless count_process_dynamic configuration provides a maximum that is greater than the process_count.
process_count_min/1 | #### Return the process count minimum of this instance of the service. This will be the same as the process_count, unless count_process_dynamic configuration provides a minimum that is less than the process_count.
process_index/1 | #### Return the 0-based index of this instance of the service. The configuration of the service defined how many instances should exist.
recv_async/1 | #### Receive an asynchronous service request. Use a null TransId to receive the oldest service request.
recv_async/2 | #### Receive an asynchronous service request. Either use the supplied TransId to receive the specific service request or use a null TransId to receive the oldest service request.
recv_async/3 | #### Receive an asynchronous service request. Either use the supplied TransId to receive the specific service request or use a null TransId to receive the oldest service request.
recv_async/4 | #### Receive an asynchronous service request. .
recv_asyncs/2 | #### Receive asynchronous service requests. .
recv_asyncs/3 | #### Receive asynchronous service requests. .
recv_asyncs/4 | #### Receive asynchronous service requests. .
return/2 | #### Return a service response. .
return/3 | #### Return a service response. .
return/9 | #### Return a service response. .
return_async/8 | #### Return an asynchronous service response. .
return_nothrow/9 | #### Return a service response without exiting the request handler. Should rarely, if ever, be used.
return_sync/8 | #### Return a synchronous service response. .
self/1 | #### Return the Erlang pid representing the service. .
send_async/3 | #### Send an asynchronous service request. .
send_async/4 | #### Send an asynchronous service request. .
send_async/5 | #### Send an asynchronous service request. .
send_async/6 | #### Send an asynchronous service request. .
send_async/7 | #### Send an asynchronous service request. .
send_async_active/3 | #### Send an asynchronous service request. The response is sent to the service as an Erlang message which is either: `{return_async_active, Name, Pattern, ResponseInfo, Response, Timeout, TransId}` (or) `{timeout_async_active, TransId}` use `-include_lib("cloudi_core/include/cloudi_service.hrl").` to have: `#return_async_active{}` (or) `#timeout_async_active{}`
send_async_active/4 | #### Send an asynchronous service request. The response is sent to the service as an Erlang message which is either: `{return_async_active, Name, Pattern, ResponseInfo, Response, Timeout, TransId}` (or) `{timeout_async_active, TransId}` use `-include_lib("cloudi_core/include/cloudi_service.hrl").` to have: `#return_async_active{}` (or) `#timeout_async_active{}`
send_async_active/5 | #### Send an asynchronous service request. The response is sent to the service as an Erlang message which is either: `{return_async_active, Name, Pattern, ResponseInfo, Response, Timeout, TransId}` (or) `{timeout_async_active, TransId}` use `-include_lib("cloudi_core/include/cloudi_service.hrl").` to have: `#return_async_active{}` (or) `#timeout_async_active{}`
send_async_active/6 | #### Send an asynchronous service request. The response is sent to the service as an Erlang message which is either: `{return_async_active, Name, Pattern, ResponseInfo, Response, Timeout, TransId}` (or) `{timeout_async_active, TransId}` use `-include_lib("cloudi_core/include/cloudi_service.hrl").` to have: `#return_async_active{}` (or) `#timeout_async_active{}`
send_async_active/7 | #### Send an asynchronous service request. The response is sent to the service as an Erlang message which is either: `{return_async_active, Name, Pattern, ResponseInfo, Response, Timeout, TransId}` (or) `{timeout_async_active, TransId}` use `-include_lib("cloudi_core/include/cloudi_service.hrl").` to have: `#return_async_active{}` (or) `#timeout_async_active{}`
send_async_active/8 | #### Send an asynchronous service request with a previously generated transaction id. Only meant for special transaction handling.
send_async_passive/3 | #### Send an asynchronous service request. An alias for send_async.
send_async_passive/4 | #### Send an asynchronous service request. An alias for send_async.
send_async_passive/5 | #### Send an asynchronous service request. An alias for send_async.
send_async_passive/6 | #### Send an asynchronous service request. An alias for send_async.
send_async_passive/7 | #### Send an asynchronous service request. An alias for send_async.
send_sync/3 | #### Send a synchronous service request. .
send_sync/4 | #### Send a synchronous service request. .
send_sync/5 | #### Send a synchronous service request. .
send_sync/6 | #### Send a synchronous service request. .
send_sync/7 | #### Send a synchronous service request. .
source_subscriptions/2 | #### Get a list of all service name patterns a service request source is subscribed to. The source pid can be found at: `cloudi_service_handle_request(_, _, _, _, _, _, _, _, Pid, _, _)`
subscribe/2 | #### Subscribe to a service name pattern. .
subscribe_count/2 | #### Determine how may service name pattern subscriptions have occurred. .
suffix/2 | #### Service request suffix from a service name or service name pattern. .
timeout_async/1 | #### Configured service default asynchronous timeout (in milliseconds). .
timeout_max/1 | #### Maximum possible service request timeout (in milliseconds). .
timeout_sync/1 | #### Configured service default synchronous timeout (in milliseconds). .
trans_id/1 | #### Return a new transaction id. The same data as used when sending service requests is used.
unsubscribe/2 | #### Unsubscribe from a service name pattern. .

## Function Details

### context_options/1

`context_options(Dispatcher::dispatcher()) -> cloudi:options()`

#### Get the context options from the service's configuration.

A service would only use this when delaying the creation of a context for child processes.

### demonitor/2

`demonitor(Dispatcher::dispatcher(), MonitorRef::reference()) -> true`

#### Demonitor an Erlang pid.

The function will make sure an Erlang pid is demonitored properly.

### demonitor/3

`demonitor(Dispatcher::dispatcher(), MonitorRef::reference(), Options::list()) -> true`

#### Demonitor an Erlang pid with options.

The function will make sure an Erlang pid is demonitored properly.

### destination_refresh_immediate/1

`destination_refresh_immediate(Dispatcher::dispatcher()) -> boolean()`

#### Configured service destination refresh is immediate.

### destination_refresh_lazy/1

`destination_refresh_lazy(Dispatcher::dispatcher()) -> boolean()`

#### Configured service destination refresh is lazy.

### dispatcher/1

`dispatcher(Dispatcher::dispatcher()) -> NewDispatcher::pid()`

#### Return the Erlang pid representing the service sender.

Use when the Dispatcher is stored and used after the current cloudi_service callback has returned. This is only necessary when storing the dispatcher within the cloudi_service_init/4 callback, for use in a different callback.

### duo_mode/1

`duo_mode(Dispatcher::dispatcher()) -> boolean()`

#### Determine if duo_mode is enabled.

### forward/9

`forward(Dispatcher::dispatcher(), RequestType::request_type(), Name::service_name(), RequestInfo::request_info(), Request::request(), Timeout::timeout_value_milliseconds(), Priority::priority(), TransId::trans_id(), Pid::pid()) -> no_return()`

#### Forward a service request.

### forward_async/8

`forward_async(Dispatcher::dispatcher(), Name::service_name(), RequestInfo::request_info(), Request::request(), Timeout::timeout_value_milliseconds(), Priority::priority(), TransId::trans_id(), Pid::pid()) -> no_return()`

#### Forward an asynchronous service request.

### forward_sync/8

`forward_sync(Dispatcher::dispatcher(), Name::service_name(), RequestInfo::request_info(), Request::request(), Timeout::timeout_value_milliseconds(), Priority::priority(), TransId::trans_id(), Pid::pid()) -> no_return()`

#### Forward a synchronous service request.

### get_pid/2

`get_pid(Dispatcher::dispatcher(), Name::service_name()) -> {ok, PatternPid::pattern_pid()} | {error, Reason::error_reason()}`

#### Get a service destination based on a service name.

### get_pid/3

`get_pid(Dispatcher::dispatcher(), Name::service_name(), Timeout::timeout_milliseconds()) -> {ok, PatternPid::pattern_pid()} | {error, Reason::error_reason()}`

#### Get a service destination based on a service name.

### get_pids/2

`get_pids(Dispatcher::dispatcher(), Name::service_name()) -> {ok, PatternPids::[pattern_pid(), ...]} | {error, Reason::error_reason()}`

#### Get all service destinations based on a service name.

### get_pids/3

`get_pids(Dispatcher::dispatcher(), Name::service_name(), Timeout::timeout_milliseconds()) -> {ok, PatternPids::[pattern_pid(), ...]} | {error, Reason::error_reason()}`

#### Get a service destination based on a service name.

### mcast_async/3

`mcast_async(Dispatcher::dispatcher(), Name::service_name(), Request::request()) -> {ok, TransIdList::[trans_id()]} | {error, Reason::error_reason()}`

#### Send a multicast asynchronous service request.

Asynchronous service requests are sent to all services that have subscribed to the service name pattern that matches the destination.

### mcast_async/4

`mcast_async(Dispatcher::dispatcher(), Name::service_name(), Request::request(), Timeout::timeout_milliseconds()) -> {ok, TransIdList::[trans_id()]} | {error, Reason::error_reason()}`

#### Send a multicast asynchronous service request.

Asynchronous service requests are sent to all services that have subscribed to the service name pattern that matches the destination.

### mcast_async/6

`mcast_async(Dispatcher::dispatcher(), Name::service_name(), RequestInfo::request_info(), Request::request(), Timeout::timeout_milliseconds(), Priority::priority()) -> {ok, TransIdList::[trans_id()]} | {error, Reason::error_reason()}`

#### Send a multicast asynchronous service request.

Asynchronous service requests are sent to all services that have subscribed to the service name pattern that matches the destination.

### mcast_async_active/3

`mcast_async_active(Dispatcher::dispatcher(), Name::service_name(), Request::request()) -> {ok, TransIdList::[trans_id()]} | {error, Reason::error_reason()}`

#### Send a multicast asynchronous service request.

Asynchronous service requests are sent to all services that have subscribed to the service name pattern that matches the destination. The responses are sent to the service as Erlang messages that are either: `{return_async_active, Name, Pattern, ResponseInfo, Response, Timeout, TransId}` (or) `{timeout_async_active, TransId}` use `-include_lib("cloudi_core/include/cloudi_service.hrl").` to have: `#return_async_active{}` (or) `#timeout_async_active{}`

### mcast_async_active/4

`mcast_async_active(Dispatcher::dispatcher(), Name::service_name(), Request::request(), Timeout::timeout_milliseconds()) -> {ok, TransIdList::[trans_id()]} | {error, Reason::error_reason()}`

#### Send a multicast asynchronous service request.

Asynchronous service requests are sent to all services that have subscribed to the service name pattern that matches the destination. The responses are sent to the service as Erlang messages that are either: `{return_async_active, Name, Pattern, ResponseInfo, Response, Timeout, TransId}` (or) `{timeout_async_active, TransId}` use `-include_lib("cloudi_core/include/cloudi_service.hrl").` to have: `#return_async_active{}` (or) `#timeout_async_active{}`

### mcast_async_active/6

`mcast_async_active(Dispatcher::dispatcher(), Name::service_name(), RequestInfo::request_info(), Request::request(), Timeout::timeout_milliseconds(), Priority::priority()) -> {ok, TransIdList::[trans_id()]} | {error, Reason::error_reason()}`

#### Send a multicast asynchronous service request.

Asynchronous service requests are sent to all services that have subscribed to the service name pattern that matches the destination. The responses are sent to the service as Erlang messages that are either: `{return_async_active, Name, Pattern, ResponseInfo, Response, Timeout, TransId}` (or) `{timeout_async_active, TransId}` use `-include_lib("cloudi_core/include/cloudi_service.hrl").` to have: `#return_async_active{}` (or) `#timeout_async_active{}`

### mcast_async_passive/3

`mcast_async_passive(Dispatcher::dispatcher(), Name::service_name(), Request::request()) -> {ok, TransIdList::[trans_id()]} | {error, Reason::error_reason()}`

#### Send a multicast asynchronous service request.

An alias for mcast_async. The asynchronous service requests are returned and handled the same way as within external services.

### mcast_async_passive/4

`mcast_async_passive(Dispatcher::dispatcher(), Name::service_name(), Request::request(), Timeout::timeout_milliseconds()) -> {ok, TransIdList::[trans_id()]} | {error, Reason::error_reason()}`

#### Send a multicast asynchronous service request.

An alias for mcast_async. The asynchronous service requests are returned and handled the same way as within external services.

### mcast_async_passive/6

`mcast_async_passive(Dispatcher::dispatcher(), Name::service_name(), RequestInfo::request_info(), Request::request(), Timeout::timeout_milliseconds(), Priority::priority()) -> {ok, TransIdList::[trans_id()]} | {error, Reason::error_reason()}`

#### Send a multicast asynchronous service request.

An alias for mcast_async. The asynchronous service requests are returned and handled the same way as within external services.

### monitor/2

`monitor(Dispatcher::dispatcher(), Pid::pid()) -> MonitorRef::reference()`

#### Monitor an Erlang pid.

The function will make sure an Erlang pid is monitored properly so the cloudi_service_handle_info/3 callback receives the monitor result. Since both the request_pid and the info_pid are temporary Erlang processes, no spawned Erlang process should be linked to the request_pid or info_pid.

### prefix/1

`prefix(Dispatcher::dispatcher()) -> Prefix::service_name_pattern()`

#### Configured service default prefix.

All subscribed/unsubscribed service names use this prefix. The prefix defines the scope of the service.

### priority_default/1

`priority_default(Dispatcher::dispatcher()) -> PriorityDefault::cloudi_service_api:priority()`

#### Configured service default priority.

### process_count/1

`process_count(Dispatcher::dispatcher()) -> ProcessCount::pos_integer()`

#### Return the initial process count of this instance of the service.

The configuration of the service defined how many instances should exist.

### process_count_max/1

`process_count_max(Dispatcher::dispatcher()) -> ProcessCountMax::pos_integer()`

#### Return the process count maximum of this instance of the service.

This will be the same as the process_count, unless count_process_dynamic configuration provides a maximum that is greater than the process_count.

### process_count_min/1

`process_count_min(Dispatcher::dispatcher()) -> ProcessCountMin::pos_integer()`

#### Return the process count minimum of this instance of the service.

This will be the same as the process_count, unless count_process_dynamic configuration provides a minimum that is less than the process_count.

### process_index/1

`process_index(Dispatcher::dispatcher()) -> ProcessIndex::non_neg_integer()`

#### Return the 0-based index of this instance of the service.

The configuration of the service defined how many instances should exist.

### recv_async/1

`recv_async(Dispatcher::dispatcher()) -> {ok, ResponseInfo::response_info(), Response::response(), TransId::trans_id()} | {error, Reason::error_reason()}`

#### Receive an asynchronous service request.

Use a null TransId to receive the oldest service request.

### recv_async/2

`recv_async(Dispatcher::dispatcher(), TransId::timeout_milliseconds() | trans_id()) -> {ok, ResponseInfo::response_info(), Response::response(), TransId::trans_id()} | {error, Reason::error_reason()}`

#### Receive an asynchronous service request.

Either use the supplied TransId to receive the specific service request or use a null TransId to receive the oldest service request.

### recv_async/3

`recv_async(Dispatcher::dispatcher(), Timeout::timeout_milliseconds() | trans_id(), TransId::trans_id() | boolean()) -> {ok, ResponseInfo::response_info(), Response::response(), TransId::trans_id()} | {error, Reason::error_reason()}`

#### Receive an asynchronous service request.

Either use the supplied TransId to receive the specific service request or use a null TransId to receive the oldest service request.

### recv_async/4

`recv_async(Dispatcher::dispatcher(), Timeout::timeout_milliseconds(), TransId::trans_id(), Consume::boolean()) -> {ok, ResponseInfo::response_info(), Response::response(), TransId::trans_id()} | {error, Reason::error_reason()}`

#### Receive an asynchronous service request.

### recv_asyncs/2

`recv_asyncs(Dispatcher::dispatcher(), TransIdList::[trans_id()]) -> {ok, [{ResponseInfo::response_info(), Response::response(), TransId::trans_id()}]} | {error, Reason::error_reason()}`

#### Receive asynchronous service requests.

### recv_asyncs/3

`recv_asyncs(Dispatcher::dispatcher(), Timeout::timeout_milliseconds(), TransIdList::[trans_id()]) -> {ok, [{ResponseInfo::response_info(), Response::response(), TransId::trans_id()}]} | {error, Reason::error_reason()}`

#### Receive asynchronous service requests.

### recv_asyncs/4

`recv_asyncs(Dispatcher::dispatcher(), Timeout::timeout_milliseconds(), TransIdList::[trans_id()], Consume::boolean()) -> {ok, [{ResponseInfo::response_info(), Response::response(), TransId::trans_id()}]} | {error, Reason::error_reason()}`

#### Receive asynchronous service requests.

### return/2

`return(Dispatcher::dispatcher(), Response::response()) -> no_return()`

#### Return a service response.

### return/3

`return(Dispatcher::dispatcher(), ResponseInfo::response_info(), Response::response()) -> no_return()`

#### Return a service response.

### return/9

`return(Dispatcher::dispatcher(), RequestType::request_type(), Name::service_name(), Pattern::service_name_pattern(), ResponseInfo::response_info(), Response::response(), Timeout::timeout_value_milliseconds(), TransId::trans_id(), Pid::pid()) -> no_return()`

#### Return a service response.

### return_async/8

`return_async(Dispatcher::dispatcher(), Name::service_name(), Pattern::service_name_pattern(), ResponseInfo::response_info(), Response::response(), Timeout::timeout_value_milliseconds(), TransId::trans_id(), Pid::pid()) -> no_return()`

#### Return an asynchronous service response.

### return_nothrow/9

`return_nothrow(Dispatcher::dispatcher(), RequestType::request_type(), Name::service_name(), Pattern::service_name_pattern(), ResponseInfo::response_info(), Response::response(), Timeout::timeout_value_milliseconds(), TransId::trans_id(), Pid::pid()) -> ok`

#### Return a service response without exiting the request handler.

Should rarely, if ever, be used. If the service has the option request_timeout_adjustment == true, the adjustment will not occur when this function is used. Also, the service's response_timeout_immediate_max option will not prevent a null response from being sent when this function is used.

### return_sync/8

`return_sync(Dispatcher::dispatcher(), Name::service_name(), Pattern::service_name_pattern(), ResponseInfo::response_info(), Response::response(), Timeout::timeout_value_milliseconds(), TransId::trans_id(), Pid::pid()) -> no_return()`

#### Return a synchronous service response.

### self/1

`self(Dispatcher::dispatcher()) -> Self::source()`

#### Return the Erlang pid representing the service.

### send_async/3

`send_async(Dispatcher::dispatcher(), Name::service_name(), Request::request()) -> {ok, TransId::trans_id()} | {error, Reason::error_reason()}`

#### Send an asynchronous service request.

### send_async/4

`send_async(Dispatcher::dispatcher(), Name::service_name(), Request::request(), Timeout::timeout_milliseconds()) -> {ok, TransId::trans_id()} | {error, Reason::error_reason()}`

#### Send an asynchronous service request.

### send_async/5

`send_async(Dispatcher::dispatcher(), Name::service_name(), Request::request(), Timeout::timeout_milliseconds(), PatternPid::pattern_pid() | undefined) -> {ok, TransId::trans_id()} | {error, Reason::error_reason()}`

#### Send an asynchronous service request.

### send_async/6

`send_async(Dispatcher::dispatcher(), Name::service_name(), RequestInfo::request_info(), Request::request(), Timeout::timeout_milliseconds(), Priority::priority()) -> {ok, TransId::trans_id()} | {error, Reason::error_reason()}`

#### Send an asynchronous service request.

### send_async/7

`send_async(Dispatcher::dispatcher(), Name::service_name(), RequestInfo::request_info(), Request::request(), Timeout::timeout_milliseconds(), Priority::priority(), PatternPid::pattern_pid() | undefined) -> {ok, TransId::trans_id()} | {error, Reason::error_reason()}`

#### Send an asynchronous service request.

### send_async_active/3

`send_async_active(Dispatcher::dispatcher(), Name::service_name(), Request::request()) -> {ok, TransId::trans_id()} | {error, Reason::error_reason()}`

#### Send an asynchronous service request.

The response is sent to the service as an Erlang message which is either: `{return_async_active, Name, Pattern, ResponseInfo, Response, Timeout, TransId}` (or) `{timeout_async_active, TransId}` use `-include_lib("cloudi_core/include/cloudi_service.hrl").` to have: `#return_async_active{}` (or) `#timeout_async_active{}`

### send_async_active/4

`send_async_active(Dispatcher::dispatcher(), Name::service_name(), Request::request(), Timeout::timeout_milliseconds()) -> {ok, TransId::trans_id()} | {error, Reason::error_reason()}`

#### Send an asynchronous service request.

The response is sent to the service as an Erlang message which is either: `{return_async_active, Name, Pattern, ResponseInfo, Response, Timeout, TransId}` (or) `{timeout_async_active, TransId}` use `-include_lib("cloudi_core/include/cloudi_service.hrl").` to have: `#return_async_active{}` (or) `#timeout_async_active{}`

### send_async_active/5

`send_async_active(Dispatcher::dispatcher(), Name::service_name(), Request::request(), Timeout::timeout_milliseconds(), PatternPid::pattern_pid() | undefined) -> {ok, TransId::trans_id()} | {error, Reason::error_reason()}`

#### Send an asynchronous service request.

The response is sent to the service as an Erlang message which is either: `{return_async_active, Name, Pattern, ResponseInfo, Response, Timeout, TransId}` (or) `{timeout_async_active, TransId}` use `-include_lib("cloudi_core/include/cloudi_service.hrl").` to have: `#return_async_active{}` (or) `#timeout_async_active{}`

### send_async_active/6

`send_async_active(Dispatcher::dispatcher(), Name::service_name(), RequestInfo::request_info(), Request::request(), Timeout::timeout_milliseconds(), Priority::priority()) -> {ok, TransId::trans_id()} | {error, Reason::error_reason()}`

#### Send an asynchronous service request.

The response is sent to the service as an Erlang message which is either: `{return_async_active, Name, Pattern, ResponseInfo, Response, Timeout, TransId}` (or) `{timeout_async_active, TransId}` use `-include_lib("cloudi_core/include/cloudi_service.hrl").` to have: `#return_async_active{}` (or) `#timeout_async_active{}`

### send_async_active/7

`send_async_active(Dispatcher::dispatcher(), Name::service_name(), RequestInfo::request_info(), Request::request(), Timeout::timeout_milliseconds(), Priority::priority(), PatternPid::pattern_pid() | undefined) -> {ok, TransId::trans_id()} | {error, Reason::error_reason()}`

#### Send an asynchronous service request.

The response is sent to the service as an Erlang message which is either: `{return_async_active, Name, Pattern, ResponseInfo, Response, Timeout, TransId}` (or) `{timeout_async_active, TransId}` use `-include_lib("cloudi_core/include/cloudi_service.hrl").` to have: `#return_async_active{}` (or) `#timeout_async_active{}`

### send_async_active/8

`send_async_active(Dispatcher::dispatcher(), Name::service_name(), RequestInfo::request_info(), Request::request(), Timeout::timeout_milliseconds(), Priority::priority(), TransId::trans_id(), PatternPid::pattern_pid()) -> {ok, TransId::trans_id()} | {error, Reason::error_reason()}`

#### Send an asynchronous service request with a previously generated transaction id.

Only meant for special transaction handling. The response is sent to the service as an Erlang message which is either: `{return_async_active, Name, Pattern, ResponseInfo, Response, Timeout, TransId}` (or) `{timeout_async_active, TransId}` use `-include_lib("cloudi_core/include/cloudi_service.hrl").` to have: `#return_async_active{}` (or) `#timeout_async_active{}`

### send_async_passive/3

`send_async_passive(Dispatcher::dispatcher(), Name::service_name(), Request::request()) -> {ok, TransId::trans_id()} | {error, Reason::error_reason()}`

#### Send an asynchronous service request.

An alias for send_async. The asynchronous service request is returned and handled the same way as within external services.

### send_async_passive/4

`send_async_passive(Dispatcher::dispatcher(), Name::service_name(), Request::request(), Timeout::timeout_milliseconds()) -> {ok, TransId::trans_id()} | {error, Reason::error_reason()}`

#### Send an asynchronous service request.

An alias for send_async. The asynchronous service request is returned and handled the same way as within external services.

### send_async_passive/5

`send_async_passive(Dispatcher::dispatcher(), Name::service_name(), Request::request(), Timeout::timeout_milliseconds(), PatternPid::pattern_pid() | undefined) -> {ok, TransId::trans_id()} | {error, Reason::error_reason()}`

#### Send an asynchronous service request.

An alias for send_async. The asynchronous service request is returned and handled the same way as within external services.

### send_async_passive/6

`send_async_passive(Dispatcher::dispatcher(), Name::service_name(), RequestInfo::request_info(), Request::request(), Timeout::timeout_milliseconds(), Priority::priority()) -> {ok, TransId::trans_id()} | {error, Reason::error_reason()}`

#### Send an asynchronous service request.

An alias for send_async. The asynchronous service request is returned and handled the same way as within external services.

### send_async_passive/7

`send_async_passive(Dispatcher::dispatcher(), Name::service_name(), RequestInfo::request_info(), Request::request(), Timeout::timeout_milliseconds(), Priority::priority(), PatternPid::pattern_pid() | undefined) -> {ok, TransId::trans_id()} | {error, Reason::error_reason()}`

#### Send an asynchronous service request.

An alias for send_async. The asynchronous service request is returned and handled the same way as within external services.

### send_sync/3

`send_sync(Dispatcher::dispatcher(), Name::service_name(), Request::request()) -> {ok, ResponseInfo::response_info(), Response::response()} | {ok, Response::response()} | {error, Reason::error_reason()}`

#### Send a synchronous service request.

### send_sync/4

`send_sync(Dispatcher::dispatcher(), Name::service_name(), Request::request(), Timeout::timeout_milliseconds()) -> {ok, ResponseInfo::response_info(), Response::response()} | {ok, Response::response()} | {error, Reason::error_reason()}`

#### Send a synchronous service request.

### send_sync/5

`send_sync(Dispatcher::dispatcher(), Name::service_name(), Request::request(), Timeout::timeout_milliseconds(), PatternPid::pattern_pid() | undefined) -> {ok, ResponseInfo::response_info(), Response::response()} | {ok, Response::response()} | {error, Reason::error_reason()}`

#### Send a synchronous service request.

### send_sync/6

`send_sync(Dispatcher::dispatcher(), Name::service_name(), RequestInfo::request_info(), Request::request(), Timeout::timeout_milliseconds(), Priority::priority()) -> {ok, ResponseInfo::response_info(), Response::response()} | {ok, Response::response()} | {error, Reason::error_reason()}`

#### Send a synchronous service request.

### send_sync/7

`send_sync(Dispatcher::dispatcher(), Name::service_name(), RequestInfo::request_info(), Request::request(), Timeout::timeout_milliseconds(), Priority::priority(), PatternPid::pattern_pid() | undefined) -> {ok, ResponseInfo::response_info(), Response::response()} | {ok, Response::response()} | {error, Reason::error_reason()}`

#### Send a synchronous service request.

### source_subscriptions/2

`source_subscriptions(Dispatcher::dispatcher(), Pid::source()) -> [service_name_pattern()]`

#### Get a list of all service name patterns a service request source is subscribed to.

The source pid can be found at:

`cloudi_service_handle_request(_, _, _, _, _, _, _, _, Pid, _, _)`

### subscribe/2

`subscribe(Dispatcher::dispatcher(), Pattern::service_name_pattern_suffix()) -> ok | error`

#### Subscribe to a service name pattern.

### subscribe_count/2

`subscribe_count(Dispatcher::dispatcher(), Pattern::service_name_pattern_suffix()) -> non_neg_integer()`

#### Determine how may service name pattern subscriptions have occurred.

### suffix/2

`suffix(Dispatcher::dispatcher(), NameOrPattern::service_name() | service_name_pattern()) -> Suffix::service_name() | service_name_pattern()`

#### Service request suffix from a service name or service name pattern.

### timeout_async/1

`timeout_async(Dispatcher::dispatcher()) -> TimeoutAsync::cloudi_service_api:timeout_send_async_value_milliseconds()`

#### Configured service default asynchronous timeout (in milliseconds).

### timeout_max/1

`timeout_max(Dispatcher::dispatcher()) -> 4294967295`

#### Maximum possible service request timeout (in milliseconds).

### timeout_sync/1

`timeout_sync(Dispatcher::dispatcher()) -> TimeoutSync::cloudi_service_api:timeout_send_sync_value_milliseconds()`

#### Configured service default synchronous timeout (in milliseconds).

### trans_id/1

`trans_id(Dispatcher::dispatcher()) -> trans_id()`

#### Return a new transaction id.

The same data as used when sending service requests is used.

### unsubscribe/2

`unsubscribe(Dispatcher::dispatcher(), Pattern::service_name_pattern_suffix()) -> ok | error`

#### Unsubscribe from a service name pattern.

Generated by EDoc