# Module cloudi

- Description
- Data Types
- Function Index
- Function Details

### CloudI Erlang Interface

.

Copyright © 2013-2021 Michael Truog

Version: 2.0.3 Dec 3 2021 17:15:32 ------------------------------------------------------------------------

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

## Description

### CloudI Erlang Interface

## Data Types

### agent()

`agent() = context() | cloudi_service:dispatcher()`

### bytestring()

`bytestring() = [byte()]`

### context()

`context() = #cloudi_context{dest_refresh = cloudi_service_api:dest_refresh(), dest_refresh_delay = cloudi_service_api:dest_refresh_delay_milliseconds(), request_name_lookup = sync | async, timeout_async = cloudi_service_api:timeout_send_async_value_milliseconds(), timeout_sync = cloudi_service_api:timeout_send_sync_value_milliseconds(), priority_default = cloudi_service_api:priority(), scope = atom(), receiver = pid(), uuid_generator = uuid:state(), cpg_data = cpg_data:state(), cpg_data_stale = boolean()}`

### dest_refresh_delay_milliseconds()

`dest_refresh_delay_milliseconds() = 101..4294967295`

### dispatcher()

`dispatcher() = cloudi_service:dispatcher()`

### error_reason()

`error_reason() = timeout`

### message_service_request()

`message_service_request() = {Type::cloudi_service_send_async | cloudi_service_send_sync, Name::service_name(), Pattern::service_name_pattern(), RequestInfo::request_info(), Request::request(), Timeout::timeout_value_milliseconds(), Priority::priority_value(), TransId::trans_id(), Source::pid()}`

### message_service_response()

`message_service_response() = {Type::cloudi_service_return_async | cloudi_service_return_sync, Name::service_name(), Pattern::service_name_pattern(), ResponseInfo::response_info(), Response::response(), Timeout::timeout_value_milliseconds(), TransId::trans_id(), Source::pid()}`

### nonempty_bytestring()

`nonempty_bytestring() = [byte(), ...]`

### options()

`options() = [{dest_refresh, cloudi_service_api:dest_refresh()} | {dest_refresh_start, dest_refresh_delay_milliseconds()} | {dest_refresh_delay, cloudi_service_api:dest_refresh_delay_milliseconds()} | {request_name_lookup, sync | async} | {timeout_async, cloudi_service_api:timeout_send_async_value_milliseconds()} | {timeout_sync, cloudi_service_api:timeout_send_sync_value_milliseconds()} | {priority_default, priority()} | {scope, atom()} | {uuid, uuid:state()} | {groups, cpg_data:state()} | {groups_scope, atom()} | {groups_static, boolean()}]`

### pattern_pid()

`pattern_pid() = {service_name_pattern(), pid()}`

### priority()

`priority() = priority_value() | undefined`

### priority_value()

`priority_value() = cloudi_service_api:priority()`

### request()

`request() = any()`

### request_info()

`request_info() = any()`

### request_type()

`request_type() = cloudi_service:request_type()`

### response()

`response() = any()`

### response_info()

`response_info() = any()`

### service_name()

`service_name() = nonempty_bytestring()`

### service_name_pattern()

`service_name_pattern() = nonempty_bytestring()`

### service_name_pattern_suffix()

`service_name_pattern_suffix() = bytestring()`

### timeout_milliseconds()

`timeout_milliseconds() = timeout_value_milliseconds() | undefined | limit_min | limit_max`

### timeout_value_milliseconds()

`timeout_value_milliseconds() = 0..4294967295`

### trans_id()

`trans_id() = <<_:128>>`

version 1 UUID

## Function Index

destination_refresh_immediate/1 | #### Configured service destination refresh is immediate. .
destination_refresh_lazy/1 | #### Configured service destination refresh is lazy. .
destinations_refresh/2 | #### Refresh destination lookup data. Called when using a lazy destination refresh method.
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 all service destinations 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_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.
new/0 | #### Create a CloudI context. .
new/1 | #### Create a CloudI context. If a lazy destination refresh method is used, make sure to receive the {cloudi_cpg_data, Groups} message and pass it to the destinations_refresh/2 function.
priority_default/1 | #### Configured service default priority. .
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_asyncs/2 | #### Receive asynchronous service requests. .
recv_asyncs/3 | #### Receive asynchronous service requests. .
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_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. .
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.
trans_id_age/1 | #### Return the age of the transaction id. The result is microseconds since the Unix epoch 1970-01-01 00:00:00.

## Function Details

### destination_refresh_immediate/1

`destination_refresh_immediate(Context::agent()) -> boolean()`

#### Configured service destination refresh is immediate.

### destination_refresh_lazy/1

`destination_refresh_lazy(Context::agent()) -> boolean()`

#### Configured service destination refresh is lazy.

### destinations_refresh/2

`destinations_refresh(Context::context(), Message::{cloudi_cpg_data, cpg_data:state()}) -> context()`

#### Refresh destination lookup data.

Called when using a lazy destination refresh method. The {cloudi_cpg_data, Groups} message is stored and processed by this function. However, if it isn't processed, the other function calls will update the Context based on any pending destination refresh messages.

### get_pid/2

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

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

### get_pid/3

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

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

### get_pids/2

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

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

### get_pids/3

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

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

### mcast_async/3

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

#### 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(Context::agent(), Name::service_name(), Request::request(), Timeout::timeout_milliseconds()) -> {{ok, TransIdList::[trans_id()]} | {error, Reason::error_reason()}, agent()}`

#### 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(Context::agent(), Name::service_name(), RequestInfo::request_info(), Request::request(), Timeout::timeout_milliseconds(), Priority::priority()) -> {{ok, TransIdList::[trans_id()]} | {error, Reason::error_reason()}, agent()}`

#### 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

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

#### 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(Context::agent(), Name::service_name(), Request::request(), Timeout::timeout_milliseconds()) -> {{ok, TransIdList::[trans_id()]} | {error, Reason::error_reason()}, agent()}`

#### 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(Context::agent(), Name::service_name(), RequestInfo::request_info(), Request::request(), Timeout::timeout_milliseconds(), Priority::priority()) -> {{ok, TransIdList::[trans_id()]} | {error, Reason::error_reason()}, agent()}`

#### 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.

### new/0

`new() -> context()`

#### Create a CloudI context.

### new/1

`new(Options::options()) -> context()`

#### Create a CloudI context.

If a lazy destination refresh method is used, make sure to receive the {cloudi_cpg_data, Groups} message and pass it to the destinations_refresh/2 function.

### priority_default/1

`priority_default(Context::agent()) -> PriorityDefault::cloudi_service_api:priority()`

#### Configured service default priority.

### recv_async/1

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

#### Receive an asynchronous service request.

Use a null TransId to receive the oldest service request. Consume is implicitly true.

### recv_async/2

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

#### 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. Consume is implicitly true.

### recv_async/3

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

#### 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. Consume is implicitly true.

### recv_asyncs/2

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

#### Receive asynchronous service requests.

### recv_asyncs/3

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

#### Receive asynchronous service requests.

### send_async/3

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

#### Send an asynchronous service request.

### send_async/4

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

#### Send an asynchronous service request.

### send_async/5

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

#### Send an asynchronous service request.

### send_async/6

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

#### Send an asynchronous service request.

### send_async/7

`send_async(Context::agent(), 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()}, agent()}`

#### Send an asynchronous service request.

### send_async_passive/3

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

#### 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(Context::agent(), Name::service_name(), Request::request(), Timeout::timeout_milliseconds()) -> {{ok, TransId::trans_id()} | {error, Reason::error_reason()}, agent()}`

#### 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(Context::agent(), Name::service_name(), Request::request(), Timeout::timeout_milliseconds(), PatternPid::pattern_pid() | undefined) -> {{ok, TransId::trans_id()} | {error, Reason::error_reason()}, agent()}`

#### 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(Context::agent(), Name::service_name(), RequestInfo::request_info(), Request::request(), Timeout::timeout_milliseconds(), Priority::priority()) -> {{ok, TransId::trans_id()} | {error, Reason::error_reason()}, agent()}`

#### 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(Context::agent(), 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()}, agent()}`

#### 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(Context::agent(), Name::service_name(), Request::request()) -> {{ok, ResponseInfo::response_info(), Response::response()} | {ok, Response::response()} | {error, Reason::error_reason()}, agent()}`

#### Send a synchronous service request.

### send_sync/4

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

#### Send a synchronous service request.

### send_sync/5

`send_sync(Context::agent(), 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()}, agent()}`

#### Send a synchronous service request.

### send_sync/6

`send_sync(Context::agent(), 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()}, agent()}`

#### Send a synchronous service request.

### send_sync/7

`send_sync(Context::agent(), 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()}, agent()}`

#### Send a synchronous service request.

### timeout_async/1

`timeout_async(Context::agent()) -> TimeoutAsync::cloudi_service_api:timeout_send_async_value_milliseconds()`

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

### timeout_max/1

`timeout_max(Context::agent()) -> 4294967295`

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

### timeout_sync/1

`timeout_sync(Context::agent()) -> TimeoutSync::cloudi_service_api:timeout_send_sync_value_milliseconds()`

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

### trans_id/1

`trans_id(Context::agent()) -> {trans_id(), agent()}`

#### Return a new transaction id.

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

### trans_id_age/1

`trans_id_age(TransId::trans_id()) -> non_neg_integer()`

#### Return the age of the transaction id.

The result is microseconds since the Unix epoch 1970-01-01 00:00:00.

Generated by EDoc