• QUICKSTART
• API
• FAQ
• Tutorials (Java)
• Download
• Source
• Support

CloudI API Documentation

CloudI API - Making a Service

• 1.0 - Introduction
• 1.1 - (initialization)
• 1.2 - (termination)
• 1.3 - subscribe
• 1.4 - subscribe_count
• 1.5 - unsubscribe
• 1.6 - get_pid (internal services only)
• 1.7 - get_pids (internal services only)
• 1.8 - send_sync
• 1.9 - send_async
• 1.10 - send_async_active (internal services only)
• 1.11 - mcast_async
• 1.12 - mcast_async_active (internal services only)
• 1.13 - recv_async
• 1.14 - recv_asyncs (internal services only)
• 1.15 - return
• 1.16 - forward
• 1.17 - poll (external services only)

CloudI Service API - Controlling CloudI

• 2.0 - Introduction
• 2.1 - acl_add
• 2.2 - acl_remove
• 2.3 - acl
• 2.4 - service_subscriptions
• 2.5 - services_add
• 2.6 - services_remove
• 2.7 - services_restart
• 2.8 - services_search
• 2.9 - services_update
• 2.10 - services
• 2.11 - nodes_set
• 2.12 - nodes_get
• 2.13 - nodes_add
• 2.14 - nodes_remove
• 2.15 - nodes_alive
• 2.16 - nodes_dead
• 2.17 - nodes
• 2.18 - logging_set
• 2.19 - logging_file_set
• 2.20 - logging_level_set
• 2.21 - logging_syslog_set
• 2.22 - logging_formatters_set
• 2.23 - logging_redirect_set
• 2.24 - logging
• 2.25 - code_path_add
• 2.26 - code_path_remove
• 2.27 - code_path

CloudI API - Making a Service

1.0 - Introduction

The CloudI API provides a simple messaging API which allows CloudI services to send requests. So, the CloudI API contains messaging primitives that can be used to emulate other messaging APIs, but normally the CloudI API is used directly. The CloudI API supports both publish/subscribe and request/reply communication in an intuitive way. It is not necessary to understand the Erlang programming language (or Elixir), to use the CloudI API since a full CloudI API implementation is provided for every supported programming language (C/C++, Elixir, Erlang, Java, JavaScript, Perl, PHP, Python, and Ruby, currently).

The CloudI API messaging is different from other messaging APIs and provides simpler integration for a few reasons:

• The CloudI service that receives a request determines whether a reply occurs (returning no response data is the same as not providing a reply)
• All required callbacks are minimal (only a single request callback is necessary for a CloudI service to handle requests) to keep CloudI services simpler, so they are less error-prone than other solutions
• Requests are not persisted to database storage to avoid persisting errors since errors are often transient and only relate to a specific context
• All CloudI API programming language integration makes CloudI services first-class processes within the Erlang VM to provide consistent functionality and fault tolerance
• Every CloudI API request contains a priority
• Every CloudI API request contains a unique v1 UUID for identifying the request and its response
• Every CloudI API request contains a timeout which is updated based on the queuing and processing delays the request encounters

The subscribe function subscribes to a service name pattern which can contain "*" wildcard characters, to accept any matching service requests. "*" within a service name pattern matches 1 or more characters, but "**" is forbidden. The send_sync function and the send_async function provide point-to-point communication based on the service name provided. When multiple services subscribe with the same service name pattern the destination is picked based on the sending service's "destination refresh method", which can be any of the following:

The "lazy" prefix and the "immediate" prefix on the destination refresh method determines whether stale data is used within the service's data or if a single lookup process is used to get the most current destination result, respectively ("lazy" is for when long-lived services are the destination but consumes more service memory, and "immediate" is for when short-lived services are the destination but creates contention for the lookup process).

When separate service processes subscribe with the same service name pattern, each subscription is used based on random selection (if both service processes are available based on the destination refresh method), when a service request is sent to the service name. If the same service subscribes with the same service name pattern more than once within a single external service thread, each subscription is used in round-robin order (first subscription is called first, so order is preserved), when the service thread receives a request for the specific service name pattern.

The mcast_async function provides publish functionality by sending a request asynchronously to all services that have subscribed to the same service name pattern. To receive an asynchronous request recv_async is used with the "TransId" (i.e., Transaction Id, a v1 UUID) or a null UUID to receive the oldest service request.

The return function is used to respond to a service request and terminate the current request handler (i.e., the service request is finished, at that point). A service can return a null response if the sending service should not receive a response, which can be used for typical response-less publish functionality. The forward function provides a new destination for the same service request, delaying the request's completion, but still terminating the current request handler.

1.1 - (initialization)

The service configuration will control the CloudI API initialization, which is done automatically, but does influence the source code. The service configuration defines the number of Operating System (OS) processes to create and the number of threads for an external service. For an internal service, the configuration defines the number of Erlang processes to create. A number specified as an integer in the configuration is the exact number of processes or threads. However, if the number is specified as a floating point number, it is used as a CPU count (i.e., Erlang scheduler count) multipler where >1.0 implies floor and <1.0 implies round. The external service APIs provide the thread_count function so that the total number of threads can be used for thread creation, with each thread holding an instance of the CloudI API (to avoid lock contention):

int cloudi_initialize_thread_count(unsigned int * const thread_count);

unsigned int CloudI::API::thread_count();

int org.cloudi.API.thread_count();

CloudI.API.thread_count();

CloudI::API->thread_count();

\CloudI\API::thread_count();

cloudi.API.thread_count()

CloudI::API.thread_count()

An internal service uses the configured initialization timeout to limit the execution time spent within the cloudi_service_init/4 cloudi_service behaviour callback function. An external service uses the configured initialization timeout to limit the execution time spent between creating an instance of the CloudI API and calling the CloudI API poll function (for the first time). During the service initialization the CloudI API functions that may not be called are: send_sync, recv_async, return and forward (i.e., send_sync and recv_async block to receive a service request response but service initialization must be asynchronous and within the initialization timeout period, return and forward are only valid when completing the handling of a service request).

If the initialization timeout is exceeded a service failure has occurred and a restart will occur (if possible) based on the configured MaxR (maximum restarts) and MaxT (maximum time period in seconds) service configuration values. If the service was configured in the CloudI configuration file (i.e., /usr/local/etc/cloudi/cloudi.conf, used when CloudI is first started) and one of the configured services fails initialization MaxR times, CloudI will shutdown to prevent erroneous operation. To avoid the fail-fast handling of the CloudI configuration file, the CloudI Service API services_add function may be used to provide service configuration (the return value will provide information about service initialization failures exceeding MaxR).

The service configuration also allows Access Control Lists (ACLs) to define explicit service name patterns for allowing or denying service destinations when the service sends a service request. The ACLs along with the destination refresh method determine how service requests are sent while other service options can tweak default settings.

External (non-Erlang) services are provided both the command line and the environmental variables specified within the service configuration. External sevice configuration uses the full path to the executable while internal services use the module name (and the OTP application name) within the code search paths. All environmental variables set in the shell executing the Erlang VM can be used within the executable path, arguments and environment set in the configuration of an external service, using standard shell syntax (e.g., "${USER}" or "$USER", where "\\$" is a literal "$" character).

Please see the CloudI Service API (services_add) for more details about service configuration.

Specific Language Integration Notes:

The Elixir/Erlang CloudI API functions shown below accept the most function parameters in cloudi_service but functions with less parameters do exist and they utilize default values for timeouts and request priority. Both the Timeout parameter and the Priority parameter accept the 'undefined' atom to assign the default configured value. Please see the cloudi_service module to see all the available functions and the behavior interface functions that are implemented within an Erlang service. The cloudi_service module is used within CloudI services, however, it is also possible to use CloudI services from external Erlang processes with a subset of the CloudI API functions in the cloudi module.

Both the C and the C++ CloudI API rely on the same underlying code, with the C++ API object as a wrapper around the C API pointer, so there should be no large performance difference. STL is avoided, to avoid the libstdc++ memory pool and internal memory pools are used. The C++ CloudI API functions below use the STRING type to represent either char const * const (or) std::string const &, since both are supported with overloaded functions.

The Java CloudI API doesn't have any C or C++ integration. It only uses reflection to utilize the low-level file descriptor object and store object function pointers.

The python CloudI API is provided as both the "cloudi" module and the "cloudi_c" module. The "cloudi_c" module uses the C++ CloudI API for more efficiency, while the "cloudi" module only uses Python source code.

1.2 - (termination)

An internal service uses the termination timeout to limit the execution time spent within the cloudi_service_terminate/3 cloudi_service behaviour callback function. An external service uses the termination timeout to limit the execution time spent between returning from the CloudI API poll function and the service OS process exit. The termination timout is slightly less than MaxT (maximum time period in seconds) divided by MaxR (maximum restarts) to make sure service failures are finite (MaxR and MaxT are both service configuration values). During termination no CloudI API functions may be called. The termination execution time is used to cleanup the service's state (e.g., close connections or files).

1.3 - subscribe

int cloudi_subscribe(cloudi_instance_t * p,
                     char const * const pattern,
                     cloudi_callback_t f);

template <typename T>
int CloudI::API::subscribe(STRING pattern,
                           T & object,
                           void (T::*f) (CloudI::API const &,
                                         int const,
                                         STRING,
                                         STRING,
                                         void const * const,
                                         uint32_t const,
                                         void const * const,
                                         uint32_t const,
                                         uint32_t,
                                         int8_t,
                                         char const * const,
                                         char const * const,
                                         uint32_t const)) const;
int CloudI::API::subscribe(STRING pattern,
                           void (*f) (API const &,
                                      int const,
                                      STRING,
                                      STRING,
                                      void const * const,
                                      uint32_t const,
                                      void const * const,
                                      uint32_t const,
                                      uint32_t,
                                      int8_t,
                                      char const * const,
                                      char const * const,
                                      uint32_t const)) const

:cloudi_service.subscribe(dispatcher, pattern)

cloudi_service:subscribe(Dispatcher :: pid(), Pattern :: string()) ->
    ok.

void org.cloudi.API.subscribe(final String pattern,
                              final Object instance,
                              final String methodName);
// with Java ≥ 8 a method reference can be used
void org.cloudi.API.subscribe(final String pattern,
                              final FunctionInterface9 callback);

var callback = function () {};
CloudI.API.subscribe(pattern, object, object_function, callback);

CloudI::API->subscribe($pattern, $function);
CloudI::API->subscribe($pattern, $object, $method);

\CloudI\API::subscribe($pattern, $object, $method);

cloudi.API.subscribe(pattern, function)

CloudI::API.subscribe(pattern, function)

Subscribes with a service name pattern which provides a destination for other services to send to. The subscribing service will receive a service request, if a different service sends a service request with a service name that matches the service name pattern. The service name pattern is a string that may contain a "*" wildcard character to match 1 or more characters, while "**" is forbidden. The service names and service name patterns are expected to be in a filepath format (e.g., "/root/directory/file.extension") by some provided CloudI services, though nothing enforces this convention. Good design dictates that service names operate within a given scope. Both the service names and the service name patterns should represent an appropriate scope, which the service manages (i.e., the same concept as a Uniform Resource Identifier (URI)).

When a service subscribes to a service name pattern, the supplied pattern string is appended to the service name prefix from the service's configuration, to provide the full service name pattern. The prefix provided within the service's configuration declares the scope of all service operations, as they are seen from other running services. Multiple subscribe function calls can increase the probability of receiving a service request when other services are subscribed with the same service name pattern.

1.4 - subscribe_count

int cloudi_subscribe_count(cloudi_instance_t * p,
                           char const * const pattern);
// cloudi_get_subscribe_count(p) to get the result

int CloudI::API::subscribe_count(STRING pattern) const;
// CloudI::API::get_subscribe_count() to get the result

:cloudi_service.subscribe_count(dispatcher, pattern)

cloudi_service:subscribe_count(Dispatcher :: pid(),
                               Pattern :: string()) ->
    non_neg_integer().

int org.cloudi.API.subscribe_count(final String pattern);
// return value is result

var callback = function (count) {};
CloudI.API.subscribe_count(pattern, callback);

CloudI::API->subscribe_count($pattern);

\CloudI\API::subscribe_count($pattern);

cloudi.API.subscribe_count(pattern)
# return value is result

CloudI::API.subscribe_count(pattern)
# return value is result

Provide a count of how many times a subscription has occurred for a specific service name pattern with the current service process. Often the result is either 0 or 1, but it is possible to subscribe any number of times to change the probability of the service process getting a service request, when many service processes are subscribing with the same service name. This function will always check the authoritative service process registry, so the result is always correct at that point in time (i.e., a lazy destination refresh method will not affect the subscribe_count result).

subscribe_count would be most common during testing and first learning about CloudI, but the function may also be used if the subscribe function usage is complex and not tracked separately (i.e., tracked within the service process' internal state).

1.5 - unsubscribe

int cloudi_unsubscribe(cloudi_instance_t * p,
                       char const * const pattern);

int CloudI::API::unsubscribe(STRING pattern) const;

:cloudi_service.unsubscribe(dispatcher, pattern)

cloudi_service:unsubscribe(Dispatcher :: pid(), Pattern :: string()) ->
    ok.

void org.cloudi.API.unsubscribe(final String pattern);

var callback = function () {};
CloudI.API.unsubscribe(pattern, callback);

CloudI::API->unsubscribe($pattern);

\CloudI\API::unsubscribe($pattern);

cloudi.API.unsubscribe(pattern)

CloudI::API.unsubscribe(pattern)

Unsubscribe will remove the service's subscription for the specific service name pattern. If a service has subscribed with the same service name pattern multiple times, the unsubscribe will only remove one subscription instance. The subscription instance which is removed is whatever subscription would have been called next, for a matching service request.

1.6 - get_pid (internal services only)

:cloudi_service.get_pid(dispatcher, name, timeout)

cloudi_service:get_pid(Dispatcher :: pid(),
                       Name :: string(),
                       Timeout :: non_neg_integer() | 'undefined' |
                                  'limit_min' | 'limit_max') ->
    {'ok', PatternPid :: {string(), pid()}} |
    {'error', Reason :: atom()}.

Internal (Elixir/Erlang-only) services can request an Erlang process based on the service name provided, before calling either the send_sync function or the send_async function. The get_pid function should rarely be necessary, but it can allow other logic to be used for determining which service should receive a request (e.g., based on apparent processing power, like within the hexpi test). The Erlang PatternPid tuple returned could become invalid if the service destination terminated, so the Erlang process monitoring becomes the burden of the get_pid function user. Due to the intimate nature of this function, it only exists within the Elixir/Erlang CloudI API (to implement it in other languages would cause service destination inconsistencies due to the function delay and the potential storage before the destination is used).

The get_pid function provides a way to split the service name lookup latency from the service request latency so that two separate timeout values can be used, instead of a single timeout.

1.7 - get_pids (internal services only)

:cloudi_service.get_pids(dispatcher, name, timeout)

cloudi_service:get_pids(Dispatcher :: pid(),
                        Name :: string(),
                        Timeout :: non_neg_integer() | 'undefined' |
                                   'limit_min' | 'limit_max') ->
    {'ok', PatternPids :: list({string(), pid()})} |
    {'error', Reason :: atom()}.

Internal (Elixir/Erlang-only) services can request a list of Erlang processes based on the service name provided, before calling either the send_sync function or the send_async function. If all Erlang processes returned need to be used with send_async, it is easier to use the mcast_async function. The get_pids function should rarely be necessary, but it can allow other logic to be used for determining which service should receive a request (e.g., based on apparent processing power, like within the hexpi test). The Erlang PatternPids tuple list returned could contain invalid Erlang processes if the service destination terminated, so the Erlang process monitoring becomes the burden of the get_pids function user. Due to the intimate nature of this function, it only exists within the Elixir/Erlang CloudI API (to implement it in other languages would cause service destination inconsistencies due to the function delay and the potential storage before the destination is used).

The get_pids function provides a way to split the service name lookup latency from the service request latency so that two separate timeout values can be used, instead of a single timeout (e.g., with mcast_async).

1.8 - send_sync

int cloudi_send_sync_(cloudi_instance_t * p,
                      char const * const name,
                      void const * const request_info,
                      uint32_t const request_info_size,
                      void const * const request,
                      uint32_t const request_size,
                      uint32_t timeout,
                      int8_t const priority);

int CloudI::API::send_sync(STRING name,
                           void const * const request_info,
                           uint32_t const request_info_size,
                           void const * const request,
                           uint32_t const request_size,
                           uint32_t timeout,
                           int8_t const priority) const;

:cloudi_service.send_sync(dispatcher, name,
                          request_info, request, timeout, priority)
:cloudi_service.send_sync(dispatcher, name,
                          request_info, request, timeout, priority,
                          pattern_pid)

cloudi_service:send_sync(Dispatcher :: pid(),
                         Name :: string(),
                         RequestInfo :: any(),
                         Request :: any(),
                         Timeout :: non_neg_integer() | 'undefined' |
                                    'limit_min' | 'limit_max',
                         Priority :: integer() | 'undefined') ->
    {'ok', ResponseInfo :: any(), Response :: any()} |
    {'ok', Response :: any()} |
    {'error', Reason :: atom()}.
cloudi_service:send_sync(Dispatcher :: pid(),
                         Name :: string(),
                         RequestInfo :: any(),
                         Request :: any(),
                         Timeout :: non_neg_integer() | 'undefined' |
                                    'limit_min' | 'limit_max',
                         Priority :: integer() | 'undefined',
                         PatternPid :: {string(), pid()}) ->
    {'ok', ResponseInfo :: any(), Response :: any()} |
    {'ok', Response :: any()} |
    {'error', Reason :: atom()}.

Response org.cloudi.API.send_sync(String name, byte[] request_info,
                                  byte[] request, Integer timeout,
                                  Byte priority);

CloudI.API.send_sync(name, request, callback,
                     timeout, request_info, priority);

CloudI::API->send_sync($name, $request,
                       $timeout, $request_info, $priority);

\CloudI\API::send_sync($name, $request,
                       $timeout = null, $request_info = null,
                       $priority = null);

cloudi.API.send_sync(name, request,
                     timeout=None, request_info=None, priority=None)

CloudI::API.send_sync(name, request,
                      timeout=nil, request_info=nil, priority=nil)

Send a synchronous request to a service name with a specific timeout and a specific priority. If a timeout is not provided, the default synchronous timeout from the service configuration is used. If a priority is not provided, the default priority from the service configuration options is used (normally the default priority is 0).

cloudi_get_response(p)
cloudi_get_response_size(p)
cloudi_get_response_info(p)
cloudi_get_response_info_size(p)
cloudi_get_trans_id_count(p)
cloudi_get_trans_id(p, i)

char const * CloudI::API::get_response() const;
uint32_t CloudI::API::get_response_size() const;
char const * CloudI::API::get_response_info() const;
uint32_t CloudI::API::get_response_info_size() const;
uint32_t CloudI::API::get_trans_id_count() const;
char const * CloudI::API::get_trans_id(unsigned int const i = 0) const;

{:ok, response_info, response}
{:ok, response}
{:error, reason}

{'ok', ResponseInfo :: any(), Response :: any()}
{'ok', Response :: any()}
{'error', Reason :: atom()}

org.cloudi.API.Response

callback(response_info, response, trans_id);

($response_info, $response, $trans_id)

array($response_info, $response, $trans_id)

(response_info, response, trans_id)

[response_info, response, trans_id]

The send_sync response data is provided in ways typical to each programming language, as shown above. The non-Erlang send_sync functions provide the TransId of the request because the calling service may need to use the v1 UUID to manipulate and/or store the response.

1.9 - send_async

int cloudi_send_async_(cloudi_instance_t * p,
                       char const * const name,
                       void const * const request_info,
                       uint32_t const request_info_size,
                       void const * const request,
                       uint32_t const request_size,
                       uint32_t timeout,
                       int8_t const priority);

int CloudI::API::send_async(STRING name,
                            void const * const request_info,
                            uint32_t const request_info_size,
                            void const * const request,
                            uint32_t const request_size,
                            uint32_t timeout,
                            int8_t const priority) const;

:cloudi_service.send_async(dispatcher, name,
                           request_info, request, timeout, priority)
:cloudi_service.send_async(dispatcher, name,
                           request_info, request, timeout, priority,
                           pattern_pid)

cloudi_service:send_async(Dispatcher :: pid(),
                          Name :: string(),
                          RequestInfo :: any(),
                          Request :: any(),
                          Timeout :: non_neg_integer() | 'undefined' |
                                    'limit_min' | 'limit_max',
                          Priority :: integer() | 'undefined') ->
    {'ok', TransId :: <<_:128>>} |
    {'error', Reason :: atom()}.
cloudi_service:send_async(Dispatcher :: pid(),
                          Name :: string(),
                          RequestInfo :: any(),
                          Request :: any(),
                          Timeout :: non_neg_integer() | 'undefined' |
                                    'limit_min' | 'limit_max',
                          Priority :: integer() | 'undefined',
                          PatternPid :: {string(), pid()}) ->
    {'ok', TransId :: <<_:128>>} |
    {'error', Reason :: atom()}.

TransId org.cloudi.API.send_async(String name, byte[] request_info,
                                  byte[] request, Integer timeout,
                                  Byte priority);

CloudI.API.send_async(name, request, callback,
                      timeout, request_info, priority);

CloudI::API->send_async($name, $request,
                        $timeout, $request_info, $priority);

\CloudI\API::send_async($name, $request,
                        $timeout = null, $request_info = null,
                        $priority = null);

cloudi.API.send_async(name, request,
                      timeout=None, request_info=None, priority=None)

CloudI::API.send_async(name, request,
                       timeout=nil, request_info=nil, priority=nil)

Send an asynchronous request to a service name with a specific timeout and a specific priority. If a timeout is not provided, the default asynchronous timeout from the service configuration is used. If a priority is not provided, the default priority from the service configuration options is used (normally the default priority is 0).

An asynchronous send will block until a live service matches the service name destination or the timeout expires (when the service configuration option request_name_lookup is set to 'sync', the default, if an asynchronous lookup is required set request_name_lookup to 'async'). Once the asynchronous request is sent the TransId which identifies the request is returned.

cloudi_get_trans_id_count(p)
cloudi_get_trans_id(p, i)

uint32_t CloudI::API::get_trans_id_count() const;
char const * CloudI::API::get_trans_id(unsigned int const i = 0) const;

{:ok, trans_id}
{:error, reason}

{'ok', TransId :: <<_:128>>}
{'error', Reason :: atom()}

org.cloudi.API.TransId

callback(trans_id);

$trans_id

$trans_id

trans_id

trans_id

The send_async result is provided in ways typical to each programming language, as shown above. A TransId is a v1 UUID.

1.10 - send_async_active (internal services only)

:cloudi_service.send_async_active(dispatcher, name,
                                  request_info, request,
                                  timeout, priority)
:cloudi_service.send_async_active(dispatcher, name,
                                  request_info, request,
                                  timeout, priority,
                                  pattern_pid)

cloudi_service:send_async_active(Dispatcher :: pid(),
                                 Name :: string(),
                                 RequestInfo :: any(),
                                 Request :: any(),
                                 Timeout :: non_neg_integer() | 'undefined' |
                                            'limit_min' | 'limit_max',
                                 Priority :: integer() | 'undefined') ->
    {'ok', TransId :: <<_:128>>} |
    {'error', atom()}.
cloudi_service:send_async_active(Dispatcher :: pid(),
                                 Name :: string(),
                                 RequestInfo :: any(),
                                 Request :: any(),
                                 Timeout :: non_neg_integer() | 'undefined' |
                                            'limit_min' | 'limit_max',
                                 Priority :: integer() | 'undefined',
                                 PatternPid :: {string(), pid()}) ->
    {'ok', TransId :: <<_:128>>} |
    {'error', atom()}.

The send_async_active function provides the same functionality as the send_async function within an Erlang process, but the response is automatically sent to the Erlang process, after completion. Using send_async_active is the preferred way to send an asynchronous service request in Erlang because it utilizes Erlang's concurrency without requiring a blocking operation (a passive send, using Erlang vernacular, since it would otherwise require a call of the function recv_async to receive the request). The send_async_active function is not implemented in other languages because of their lack of native event handling.

{:return_async_active, name, pattern,
 response_info, response, timeout, trans_id}
{:timeout_async_active, trans_id}

{'return_async_active', Name :: string(), Pattern :: string(),
 ResponseInfo :: any(), Response :: any(),
 Timeout :: non_neg_integer(), TransId :: <<_:128>>}
{'timeout_async_active', TransId :: <<_:128>>}

The send_async_active message is sent to the Erlang process as an Erlang message, so it arrives in the cloudi_service_handle_info function of the Erlang service module (i.e., the module that implements the cloudi_service behavior). The message formats are also provided as records that are accessible with:

-include_lib("cloudi_core/include/cloudi_service.hrl").

1.11 - mcast_async

int cloudi_mcast_async_(cloudi_instance_t * p,
                        char const * const name,
                        void const * const request_info,
                        uint32_t const request_info_size,
                        void const * const request,
                        uint32_t const request_size,
                        uint32_t timeout,
                        int8_t const priority);

int CloudI::API::mcast_async(STRING name,
                             void const * const request_info,
                             uint32_t const request_info_size,
                             void const * const request,
                             uint32_t const request_size,
                             uint32_t timeout,
                             int8_t const priority) const;

:cloudi_service.mcast_async(dispatcher, name,
                            request_info, request, timeout, priority)

cloudi_service:mcast_async(Dispatcher :: pid(),
                           Name :: string(),
                           RequestInfo :: any(),
                           Request :: any(),
                           Timeout :: non_neg_integer() | 'undefined' |
                                      'limit_min' | 'limit_max',
                           Priority :: integer() | 'undefined') ->
    {'ok', TransIdList :: list(<<_:128>>)} |
    {'error', Reason :: atom()}.

List<TransId> org.cloudi.API.mcast_async(String name,
                                         byte[] request_info,
                                         byte[] request,
                                         Integer timeout,
                                         Byte priority);

CloudI.API.mcast_async(name, request, callback,
                       timeout, request_info, priority);

CloudI::API->mcast_async($name, $request,
                         $timeout, $request_info, $priority);

\CloudI\API::mcast_async($name, $request,
                         $timeout = null, $request_info = null,
                         $priority = null);

cloudi.API.mcast_async(name, request,
                       timeout=None, request_info=None, priority=None)

CloudI::API.mcast_async(name, request,
                        timeout=nil, request_info=nil, priority=nil)

Multicast asynchronously, which is the same as publish, except that it is possible to respond to the service request. The function mcast_async will send the service request asynchronously to all services that have subscribed to a service name pattern that matches the service name destination. The mcast_async function will block until at least a single request has been sent or the timeout has expired (when the service configuration option request_name_lookup is set to 'sync', the default, if an asynchronous lookup is required set request_name_lookup to 'async'). The result of the function call is a list of TransIds (one TransId per service request). If a publish request is required, the destination service should have a null response, so that the service request response is ignored.

cloudi_get_trans_id_count(p)
cloudi_get_trans_id(p, i)

uint32_t CloudI::API::get_trans_id_count() const;
char const * CloudI::API::get_trans_id(unsigned int const i = 0) const;

{:ok, trans_id_list}
{:error, reason}

{'ok', TransIdList :: list(<<_:128>>)}
{'error', Reason :: atom()}

List<org.cloudi.API.TransId>

callback(trans_ids);

@trans_ids

$trans_ids

[trans_id]

[trans_id]

The mcast_async result is provided in ways typical to each programming language, as shown above. A TransId is a v1 UUID.

1.12 - mcast_async_active (internal services only)

:cloudi_service.mcast_async_active(dispatcher, name,
                                   request_info, request,
                                   timeout, priority)

cloudi_service:mcast_async_active(Dispatcher :: pid(),
                                  Name :: string(),
                                  RequestInfo :: any(),
                                  Request :: any(),
                                  Timeout :: non_neg_integer() | 'undefined' |
                                             'limit_min' | 'limit_max',
                                  Priority :: integer() |
                                              'undefined') ->
    {'ok', TransIdList :: list(<<_:128>>)} |
    {'error', Reason :: atom()}.

The mcast_async_active function provides the same functionality as the mcast_async function within an Erlang process, but the response is automatically sent to the Erlang process, after completion. Using mcast_async_active is the preferred way to publish an asynchronous service request in Erlang because it utilizes Erlang's concurrency without requiring a blocking operation (a passive send, using Erlang vernacular, since it would otherwise require a call of the function recv_async to receive the request). The mcast_async_active function is not implemented in other languages because of their lack of native event handling.

{:return_async_active, name, pattern,
 response_info, response, timeout, trans_id}
{:timeout_async_active, trans_id}

{'return_async_active', Name :: string(), Pattern :: string(),
 ResponseInfo :: any(), Response :: any(),
 Timeout :: non_neg_integer(), TransId :: <<_:128>>}
{'timeout_async_active', TransId :: <<_:128>>}

The mcast_async_active message is sent to the Erlang process as an Erlang message, so it arrives in the cloudi_service_handle_info function of the Erlang service module (i.e., the module that implements the cloudi_service behavior). The message formats are also provided as records that are accessible with:

-include_lib("cloudi_core/include/cloudi_service.hrl").

1.13 - recv_async

int cloudi_recv_async(cloudi_instance_t * p,
                      uint32_t timeout,
                      char const * const trans_id,
                      int consume);

int CloudI::API::recv_async(uint32_t timeout,
                            STRING trans_id,
                            bool consume) const;

:cloudi_service.recv_async(dispatcher, timeout, trans_id, consume)

cloudi_service:recv_async(Dispatcher :: pid(),
                          Timeout :: non_neg_integer() | 'undefined' |
                                     'limit_min' | 'limit_max',
                          TransId :: <<_:128>>,
                          Consume :: boolean()) ->
    {'ok', ResponseInfo :: any(), Response :: any(),
           TransId :: <<_:128>>} |
    {'error', Reason :: atom()}.

Response org.cloudi.API.recv_async(Integer timeout, byte[] transId,
                                   boolean consume);

CloudI.API.recv_async(callback,
                      timeout, trans_id, consume);

CloudI::API->recv_async($timeout, $trans_id, $consume);

\CloudI\API::recv_async($timeout = null, $trans_id = null,
                        $consume = true);

cloudi.API.recv_async(timeout=None, trans_id=None, consume=True)

CloudI::API.recv_async(timeout=nil, trans_id=nil, consume=true)

Receive an asynchronous service request's response. If a TransId is not provided, a null UUID is used to request the oldest response that has not timed out. By default, the recv_async function will consume the service request so it is not accessible with the same function call in the future. The TransId of the service request is always returned for any external use or tracking of the request or response.

cloudi_get_response(p)
cloudi_get_response_size(p)
cloudi_get_response_info(p)
cloudi_get_response_info_size(p)
cloudi_get_trans_id_count(p)
cloudi_get_trans_id(p, i)

char const * CloudI::API::get_response() const;
uint32_t CloudI::API::get_response_size() const;
char const * CloudI::API::get_response_info() const;
uint32_t CloudI::API::get_response_info_size() const;
uint32_t CloudI::API::get_trans_id_count() const;
char const * CloudI::API::get_trans_id(unsigned int const i = 0) const;

{:ok, response_info, response, trans_id}
{:error, reason}

{'ok', ResponseInfo :: any(), Response :: any(),
       TransId :: <<_:128>>}
{'error', Reason :: atom()}

org.cloudi.API.Response

callback(response_info, response, trans_id);

($response_info, $response, $trans_id)

array($response_info, $response, $trans_id)

(response_info, response, trans_id)

[response_info, response, trans_id]

1.14 - recv_asyncs (internal services only)

:cloudi_service.recv_asyncs(dispatcher,
                            timeout, trans_id_list, consume)

cloudi_service:recv_asyncs(Dispatcher :: pid(),
                           Timeout :: non_neg_integer() | 'undefined' |
                                      'limit_min' | 'limit_max',
                           TransIdList :: list(<<_:128>>),
                           Consume :: boolean()) ->
    {'ok', list({ResponseInfo :: any(), Response :: any(),
                 TransId :: <<_:128>>})} |
    {'error', Reason :: atom()}.

Internal (Elixir/Erlang-only) services can block to receive multiple asynchronous service request responses. By default, the recv_asyncs function will consume the service request so it is not accessible with the same function call in the future. The TransId of the service request is always returned for any external use or tracking of the request or response. The recv_asyncs function is not implemented in other languages to avoid unbounded memory consumption and caching/heap allocation impossibilities.

1.15 - return

int cloudi_return(cloudi_instance_t * p,
                  int const command,
                  char const * const name,
                  char const * const pattern,
                  void const * const response_info,
                  uint32_t const response_info_size,
                  void const * const response,
                  uint32_t const response_size,
                  uint32_t timeout,
                  char const * const trans_id,
                  char const * const pid,
                  uint32_t const pid_size);

int CloudI::API::return_(int const command,
                         STRING name,
                         STRING pattern,
                         void const * const response_info,
                         uint32_t const response_info_size,
                         void const * const response,
                         uint32_t const response_size,
                         uint32_t timeout,
                         char const * const trans_id,
                         char const * const pid,
                         uint32_t const pid_size) const;

:cloudi_service.return(dispatcher, type, name, pattern,
                       response_info, response,
                       timeout, trans_id, pid)

cloudi_service:return(Dispatcher :: pid(),
                      Type :: 'send_async' | 'send_sync',
                      Name :: string(),
                      Pattern :: string(),
                      ResponseInfo :: any(),
                      Response :: any(),
                      Timeout :: non_neg_integer(),
                      TransId :: <<_:128>>,
                      Pid :: pid()) ->
    none().

void org.cloudi.API.return_(Integer command,
                            String name, String pattern,
                            byte[] response_info, byte[] response,
                            Integer timeout, byte[] transId,
                            OtpErlangPid pid);

CloudI.API.return_(command, name, pattern,
                   response_info, response, timeout, trans_id, pid);

CloudI::API->return_($command, $name, $pattern,
                     $response_info, $response,
                     $timeout, $trans_id, $pid);

\CloudI\API::return_($command, $name, $pattern,
                     $response_info, $response,
                     $timeout, $trans_id, $pid);

cloudi.API.return_(command, name, pattern, response_info, response,
                   timeout, trans_id, pid)

CloudI::API.return_(command, name, pattern, response_info, response,
                    timeout, trans_id, pid)

Return a response to a service request. The return function will throw a caught exception so that the request handler execution is aborted after returning the service request response. The simplest and preferred way to return a response within an Erlang service is to utilize the cloudi_service_handle_request functon return values used by the cloudi_service behavior. You can also utilize the request handler return value for the response in the programming languages Java, Python, and Ruby. However, within the external services it is more explicit (i.e., easier to understand the source code) when the source code uses the return functions.

If the service is configured with the request_timeout_adjustment option set to true (the default is false), the request handler execution time will automatically decrement the request timeout, after the request has been handled. If the service is configured with the response_timeout_adjustment option set to true (the default is false), the response timeout is automatically decremented based on the sender-side's timing (more accurate).

1.16 - forward

int cloudi_forward(cloudi_instance_t * p,
                   int const command,
                   char const * const name,
                   void const * const request_info,
                   uint32_t const request_info_size,
                   void const * const request,
                   uint32_t const request_size,
                   uint32_t timeout,
                   int8_t const priority,
                   char const * const trans_id,
                   char const * const pid,
                   uint32_t const pid_size);

int CloudI::API::forward_(int const command,
                          STRING name,
                          void const * const request_info,
                          uint32_t const request_info_size,
                          void const * const request,
                          uint32_t const request_size,
                          uint32_t timeout,
                          int8_t const priority,
                          char const * const trans_id,
                          char const * const pid,
                          uint32_t const pid_size) const;

:cloudi_service.forward(dispatcher, type, name,
                        request_info, request,
                        timeout, priority, trans_id, pid)

cloudi_service:forward(Dispatcher :: pid(),
                       Type :: 'send_async' | 'send_sync',
                       Name :: string(),
                       RequestInfo :: any(),
                       Request :: any(),
                       Timeout :: non_neg_integer(),
                       Priority :: integer(),
                       TransId :: <<_:128>>,
                       Pid :: pid()) ->
    none().

Response org.cloudi.API.forward_(Integer command, String name,
                                 byte[] request_info, byte[] request,
                                 Integer timeout, Byte priority,
                                 byte[] transId, OtpErlangPid pid);

CloudI.API.forward_(command, name, request_info, request,
                    timeout, priority, trans_id, pid);

CloudI::API->forward_($command, $name, $request_info, $request,
                      $timeout, $priority, $trans_id, $pid);

\CloudI\API::forward_($command, $name, $request_info, $request,
                      $timeout, $priority, $trans_id, $pid);

cloudi.API.forward_(command, name, request_info, request,
                    timeout, priority, trans_id, pid)

CloudI::API.forward_(command, name, request_info, request,
                     timeout, priority, trans_id, pid)

Forward the service request to a different destination, possibly with different parameters (e.g., a completely different request). The forward function will throw a caught exception so that the request handler execution is aborted after forwarding the service request. The simplest and preferred way to forward a request within an Erlang service is to utilize the cloudi_service_handle_request functon return values used by the cloudi_service behavior. All external services must use a forward function when forwarding a request.

If the service is configured with the request_timeout_adjustment option set to true (the default is false), the request handler execution time will automatically decrement the request timeout, after the request has been handled. If the service is configured with the response_timeout_adjustment option set to true (the default is false), the response timeout is automatically decremented based on the sender-side's timing (more accurate).

1.17 - poll (external services only)

int cloudi_poll(cloudi_instance_t * p,
                int timeout);

int CloudI::API::poll(int timeout = -1);

Object org.cloudi.API.poll(int timeout);

var callback = function (timeout_) {};
CloudI.API.poll(callback, timeout);

CloudI::API->poll($timeout);

\CloudI\API::poll($timeout = -1);

cloudi.API.poll(timeout=-1)

CloudI::API.poll(timeout=nil)

External services use the poll function to accept service requests while blocking execution until either the timeout value expires or the service terminates. The execution time before the first poll function call is service initialization. The timeout value is specified in milliseconds. A timeout value of 0 can be used to not block on the poll function call. If the timeout value is not provided a value of -1 is used to make the poll function call block until service termination (if the programming language allows default function argument or function overloading). A boolean true value is used as the poll function return value if a timeout occurred (a non zero return value if the return value is an integer). A boolean false value is used as the poll function return value if service termination is in-progress.

CloudI Service API - Controlling CloudI

2.0 - Introduction

When CloudI is first started, the configuration file at /usr/local/etc/cloudi/cloudi.conf is used to determine what Access Control Lists (ACLs) should be used for services, what services should be started, what nodes should be connected, and what logging should occur. All the configuration functionality for CloudI can be done dynamically, after startup, with the CloudI Service API. A typical way to use the Service API is with either erlang terms or JSON-RPC over HTTP (using cloudi_service_api_requests and cloudi_service_http_cowboy). The CloudI Service API can also be accessed directly within the Erlang VM by using the cloudi_service_api module.

The data returned in both examples is Erlang terms within a string. All of the examples below use the Erlang protocol.

2.1 - acl_add

curl -X POST -d '[{sensitive, ["/accouting/", "/finance/"]}]' http://localhost:6464/cloudi/api/rpc/acl_add.erl

Add more ACL entries to be later used when starting services. An ACL entry is an Erlang atom() -> list(atom() | string()) relationship which provides a logical grouping of service name patterns (e.g., {api, ["/cloudi/api/"]}). When providing a service name pattern for an ACL entry, a non-pattern will be assumed to be a prefix (i.e., "/cloudi/api/" == "/cloudi/api/*").

2.2 - acl_remove

curl -X POST -d '[sensitive]' http://localhost:6464/cloudi/api/rpc/acl_remove.erl

Remove ACL entries that are no longer needed. Running services will retain their configuration, so this impacts services that are started in the future.

2.3 - acl

curl http://localhost:6464/cloudi/api/rpc/acl.erl

List all the current ACL entries as lists of service name patterns.

2.4 - service_subscriptions

curl -X POST -d '"6a675470-7a1f-11e2-d40e-a5dd00000058"' http://localhost:6464/cloudi/api/rpc/service_subscriptions.erl

List the subscriptions a service instance has initiated.

2.5 - services_add

curl -X POST -d '[{internal, "/tests/http_req/", cloudi_service_request_rate, [{service_name, "/tests/http_req/ruby.xml/get"}, {request_rate, dynamic}], lazy_closest, 5000, 5000, 5000, undefined, undefined, 1, 5, 300, [{duo_mode, true}]}]' http://localhost:6464/cloudi/api/rpc/services_add.erl

Start services and return their Service UUIDs. Provide service configuration using the same syntax found in the configuration file (i.e., /usr/local/etc/cloudi/cloudi.conf). Internal services will need to be located in a code path that the running Erlang VM is aware of (see code_path_add). The syntax of the configuration entries is shown below:

% proplist format with cloudi_service_api types
[{type, internal | external},               % inferred from module or file_path
 {prefix, cloudi:service_name_pattern()},   % default is "/"
 {module, atom() | file:filename()},        % internal service only
 {file_path, file:filename()},              % external service only
 {args, list()},                            % default is []
 {env, list({string(), string()})},         % default is []
 {dest_refresh, dest_refresh()},            % default is immediate_closest
 {protocol, default | local | tcp | udp},   % default is local
 {buffer_size, default | pos_integer()},    % default is 16384 bytes
 {timeout_init, 101..4294967195},           % default is 5000 milliseconds
 {timeout_async, 499..4294967195},          % default is 5000 milliseconds
 {timeout_sync, 499..4294967195},           % default is 5000 milliseconds
 {dest_list_deny, dest_list()},             % default is undefined
 {dest_list_allow, dest_list()},            % default is undefined
 {count_process, pos_integer() | float()},  % default is 1
 {count_thread, pos_integer() | float()},   % default is 1
 {max_r, non_neg_integer()},                % default is 5
 {max_t, seconds()},                        % default is 300 seconds
 {options, service_options_internal() |     % default is []
           service_options_external()}]

% internal service tuple format
{internal,
 (ServiceNamePrefix),
 (ErlangModuleName),
 (ModuleInitializationList),
 (DestinationRefreshMethod),
 (InitializationTimeout in milliseconds),
 (DefaultAsynchronousTimeout in milliseconds),
 (DefaultSynchronousTimeout in milliseconds),
 (DestinationDenyACL),
 (DestinationAllowACL),
 (ProcessCount),
 (MaxR),
 (MaxT in seconds),
 (ServiceOptionsPropList)}

% external service tuple format
{external,
 (ServiceNamePrefix),
 (ExecutableFilePath),
 (ExecutableCommandLineArguments),
 (ExecutableEnvironmentalVariables),
 (DestinationRefreshMethod),
 (Protocol, use 'default'),
 (ProtocolBufferSize, use 'default'),
 (InitializationTimeout in milliseconds),
 (DefaultAsynchronousTimeout in milliseconds),
 (DefaultSynchronousTimeout in milliseconds),
 (DestinationDenyACL),
 (DestinationAllowACL),
 (ProcessCount),
 (ThreadCount),
 (MaxR),
 (MaxT in seconds),
 (ServiceOptionsPropList)}

The ACL lists contain either atoms that reference the current ACL configuration or strings. If an ACL string is not a pattern, it is assumed to be a prefix (i.e., "*" is appended to make it a pattern). The ProcessCount and ThreadCount can be specified as integers for an exact count or as a floating point number to provide a CPU multiplier (X < 1.0 is round, X > 1.0 is floor). MaxR is the maximum restarts allowed within MaxT seconds (same parameters used by Erlang supervisors). The ServiceOptionsPropList provides the configurable defaults:

Timeout configuration values in milliseconds may be provided as 'limit_min' or 'limit_max' to use the extreme values (be careful, since 'limit_max' is the equivalent of 49.7 days and no one wants to wait 49.7 days to discover a failure). This is possible with the configuration values timeout_init, timeout_async, timeout_sync and the service configuration options values request_timeout_immediate_max, response_timeout_immediate_max, timeout_terminate, restart_delay, monkey_latency .

rate_request_max:

count_process_dynamic:

restart_delay:

monkey_latency:

monkey_chaos:

limit: (see your OS manpage for setrlimit to check availability)

The value for any option can be an integer or 'infinity' to set the current limit or a list to set both the current and the maximum (setting the maximum requires that the owner of the external service has permission to set the maximum limit) (e.g., {limit, [{stack, [{current, 8388608}, {maximum, infinity}]}]}).

owner:

Set the owner of an external service's OS processes.

cgroup:

Set the cgroup membership of an external service's OS processes.

aspects_init_after:

Provide a list of functions with the type signature shown below, with each function as either an anonymous Erlang function or an Erlang tuple "{module(), FunctionName :: atom()}". Will not be called if initialization does not occur successfully (aspects_terminate_before will still be called with the State as 'undefined').

Service Type	Function
Internal	fun((Args :: list(), Prefix :: cloudi_service:service_name_pattern(), Timeout :: cloudi_service_api:timeout_milliseconds(), State :: any(), Dispatcher :: cloudi_service:dispatcher()) -> {ok, NewState :: any()} | {stop, Reason :: any(), NewState :: any()}).
External	% the first function call has State =:= undefined fun((CommandLine :: list(string()), Prefix :: cloudi:service_name_pattern(), Timeout :: cloudi_service_api:timeout_milliseconds(), State :: any()) -> {ok, NewState :: any()} | {stop, Reason :: any(), NewState :: any()}).

It is also possible to use the Erlang tuple "{{module(), FunctionName :: atom()}}" to specify an arity 0 function that returns an anonymous function as described above.

aspects_request_before:

Provide a list of functions with the type signature shown below, with each function as either an anonymous Erlang function or an Erlang tuple "{module(), FunctionName :: atom()}".

Service Type	Function
Internal	fun((Type :: cloudi_service:request_type(), Name :: cloudi_service:service_name(), Pattern :: cloudi_service:service_name_pattern(), RequestInfo :: cloudi_service:request_info(), Request :: cloudi_service:request(), Timeout :: cloudi_service:timeout_value_milliseconds(), Priority :: cloudi_service:priority(), TransId :: cloudi_service:trans_id(), Source :: cloudi_service:source(), State :: any(), Dispatcher :: cloudi_service:dispatcher()) -> {ok, NewState :: any()} | {stop, Reason :: any(), NewState :: any()}).
External	fun((Type :: cloudi_service:request_type(), Name :: cloudi_service:service_name(), Pattern :: cloudi_service:service_name_pattern(), RequestInfo :: cloudi_service:request_info(), Request :: cloudi_service:request(), Timeout :: cloudi_service:timeout_value_milliseconds(), Priority :: cloudi_service:priority(), TransId :: cloudi_service:trans_id(), Source :: cloudi_service:source(), State :: any()) -> {ok, NewState :: any()} | {stop, Reason :: any(), NewState :: any()}).

It is also possible to use the Erlang tuple "{{module(), FunctionName :: atom()}}" to specify an arity 0 function that returns an anonymous function as described above.

aspects_request_after:

Provide a list of functions with the type signature shown below, with each function as either an anonymous Erlang function or an Erlang tuple "{module(), FunctionName :: atom()}".

Service Type	Function
Internal	fun((Type :: cloudi_service:request_type(), Name :: cloudi_service:service_name(), Pattern :: cloudi_service:service_name_pattern(), RequestInfo :: cloudi_service:request_info(), Request :: cloudi_service:request(), Timeout :: cloudi_service:timeout_value_milliseconds(), Priority :: cloudi_service:priority(), TransId :: cloudi_service:trans_id(), Source :: cloudi_service:source(), Result :: cloudi_service:request_result(), State :: any(), Dispatcher :: cloudi_service:dispatcher()) -> {ok, NewState :: any()} | {stop, Reason :: any(), NewState :: any()}).
External	fun((Type :: cloudi_service:request_type(), Name :: cloudi_service:service_name(), Pattern :: cloudi_service:service_name_pattern(), RequestInfo :: cloudi_service:request_info(), Request :: cloudi_service:request(), Timeout :: cloudi_service:timeout_value_milliseconds(), Priority :: cloudi_service:priority(), TransId :: cloudi_service:trans_id(), Source :: cloudi_service:source(), Result :: cloudi_service:request_result(), State :: any()) -> {ok, NewState :: any()} | {stop, Reason :: any(), NewState :: any()}).

It is also possible to use the Erlang tuple "{{module(), FunctionName :: atom()}}" to specify an arity 0 function that returns an anonymous function as described above.

aspects_info_before:

Provide a list of functions with the type signature shown below, with each function as either an anonymous Erlang function or an Erlang tuple "{module(), FunctionName :: atom()}".

Service Type	Function
Internal	fun((Request :: any(), State :: any(), Dispatcher :: cloudi_service:dispatcher()) -> {ok, NewState :: any()} | {stop, Reason :: any(), NewState :: any()}).

It is also possible to use the Erlang tuple "{{module(), FunctionName :: atom()}}" to specify an arity 0 function that returns an anonymous function as described above.

aspects_info_after:

Provide a list of functions with the type signature shown below, with each function as either an anonymous Erlang function or an Erlang tuple "{module(), FunctionName :: atom()}".

Service Type	Function
Internal	fun((Request :: any(), State :: any(), Dispatcher :: cloudi_service:dispatcher()) -> {ok, NewState :: any()} | {stop, Reason :: any(), NewState :: any()}).

It is also possible to use the Erlang tuple "{{module(), FunctionName :: atom()}}" to specify an arity 0 function that returns an anonymous function as described above.

aspects_terminate_before:

Provide a list of functions with the type signature shown below, with each function as either an anonymous Erlang function or an Erlang tuple "{module(), FunctionName :: atom()}". Will still be called if initialization does not occur successfully (with State as 'undefined').

Service Type	Function
Internal and External	fun((Reason :: any(), Timeout :: cloudi_service_api:timeout_milliseconds(), State :: any()) -> {ok, State :: any()}).

It is also possible to use the Erlang tuple "{{module(), FunctionName :: atom()}}" to specify an arity 0 function that returns an anonymous function as described above.

hibernate:

Please see the configuration file /usr/local/etc/cloudi/cloudi.conf for more specific examples.

2.6 - services_remove

curl -X POST -d '["6e81f0a6-7a1f-11e2-d40e-a5dd00000058", "6e81f0ec-7a1f-11e2-d40e-a5dd00000058"]' http://localhost:6464/cloudi/api/rpc/services_remove.erl

Provide the Service UUIDs for the services that should be stopped. The Service UUID is shown in the output of services. When the service is stopped, its running instance is removed from CloudI, but does not impact any other running instances (even if they are the same service module or binary).

When an internal service is removed and it is the last instance of the service module, the service module is purged to avoid later module conflicts. All instances of the internal service module should be configured in the same way (either a single module, an application, or a release with an application), so that the last instance is removed completely. If an application was used that is named the same as the service module, the application and its dependencies are removed (applications are stopped, modules are purged, and applications are unloaded) if the dependencies are not utilized by other applications. The same occurs if a release was used to start an application that contains the service module (the single top-level application of the release is used to determine dependencies, where the single top-level application within the release is the application that includes the service module).

2.7 - services_restart

curl -X POST -d '["6a675470-7a1f-11e2-d40e-a5dd00000058"]' http://localhost:6464/cloudi/api/rpc/services_restart.erl

Provide the Service UUIDs for the services that should be restarted. The Service UUID is shown in the output of services. When the service is restarted, the old instance is stopped and a new instance is started. During the restart delay, it is possible to lose queued service requests and received asynchronous responses. Keeping the state separate between the service instances is important to prevent failures within the new instance.

2.8 - services_search

curl -X POST -d '"/tests/http/text/post"' http://localhost:6464/cloudi/api/rpc/services_search.erl

curl -X POST -d '{cloudi_service_msg_size, "/tests/msg_size/erlang"}' http://localhost:6464/cloudi/api/rpc/services_search.erl

List the service configuration parameters with each service's UUID that are receiving service requests for a given service name. To search within a custom scope, provide both the scope and the service name within a tuple.

2.9 - services_update

curl -X POST -d '[{"", [{module, cloudi_service_messaging_sequence1}, {modules_load, [cloudi_service_messaging_sequence1]}, {sync, false}]}]' http://localhost:6464/cloudi/api/rpc/services_update.erl

Update services while they are running without any interruption in their operation. Each update that should occur is specified as a {UUID, Options} pair with the Options being described below:

% internal service update options
[{type, internal},
 {module, atom()},                            % only required field
 {module_state, module_state_internal()},     % update service state
 {sync, boolean()},                           % defaults to true
 {modules_load, list(atom())},                % defaults to []
 {modules_unload, list(atom())},              % defaults to []
 {code_paths_add, list(string())},            % defaults to []
 {code_paths_remove, list(string())},         % defaults to []
 {dest_refresh, dest_refresh()},              % update service configuration
 {timeout_init, timeout_milliseconds()},      % update service configuration
 {timeout_async, timeout_milliseconds()},     % update service configuration
 {timeout_sync, timeout_milliseconds()},      % update service configuration
 {dest_list_deny, dest_list()},               % update service configuration
 {dest_list_allow, dest_list()},              % update service configuration
 {options, service_update_plan_options_internal()}] % update service configuration options

Internal service updates require a module field provide the service module name. If the module is used in more than one service instance, provide the service UUID as "" to make sure the update applies to all service instances that use the module. If the module needs to be reloaded, it must be added to the modules_load list and the new module will be loaded using Erlang hot-code loading during the update. If the service state needs to be modified during the update, a function can be provided in the module_state field.

The module_state value for an internal service update can be provided as an anonymous Erlang function or an Erlang tuple "{module(), FunctionName :: atom()}" with the types below:

fun((OldModuleVersion :: list(any()),
     NewModuleVersion :: list(any()),
     OldState :: any()) ->
    {ok, NewState :: any()} |
    {error, Reason :: any()}).

External service updates require either the type be set to external or that the file_path, args, or env field be set (to cause the OS process of the external service to restart during the update).

% external service update options
[{type, external},
 {file_path, string()},                       % restarts OS process
 {args, string()},                            % restarts OS process
 {env, list({string(), string()})},           % restarts OS process
 {sync, boolean()},                           % defaults to true
 {modules_load, list(atom())},                % defaults to []
 {modules_unload, list(atom())},              % defaults to []
 {code_paths_add, list(string())},            % defaults to []
 {code_paths_remove, list(string())},         % defaults to []
 {dest_refresh, dest_refresh()},              % update service configuration
 {timeout_init, timeout_milliseconds()},      % update service configuration
 {timeout_async, timeout_milliseconds()},     % update service configuration
 {timeout_sync, timeout_milliseconds()},      % update service configuration
 {dest_list_deny, dest_list()},               % update service configuration
 {dest_list_allow, dest_list()},              % update service configuration
 {options, service_update_plan_options_external()}] % update service configuration options

The sync field is used to determine whether the update occurs while no service processes are processing a service request. If global state is being used while handling a service request, it is safest to have sync set to true, which is the default. If a service sends synchronous service requests to itself, the update can timeout when sync is set to true but can succeed with sync set to false.

A subset of the service configuration options can be updated:

% internal service configuration options that are updatable
[{priority_default, priority()} |
 {queue_limit, undefined | non_neg_integer()} |
 {queue_size, undefined | pos_integer()} |
 {rate_request_max,
  list({period, period_seconds()} |
       {value, number()}) | number() | undefined} |
 {dest_refresh_start, dest_refresh_delay_milliseconds()} |
 {dest_refresh_delay, dest_refresh_delay_milliseconds()} |
 {request_name_lookup, sync | async} |
 {request_timeout_adjustment, boolean()} |
 {request_timeout_immediate_max,
  request_timeout_immediate_max_milliseconds()} |
 {response_timeout_adjustment, boolean()} |
 {response_timeout_immediate_max,
  response_timeout_immediate_max_milliseconds()} |
 {monkey_latency,
  list({time_uniform_min, latency_time_milliseconds()} |
       {time_uniform_max, latency_time_milliseconds()} |
       {time_gaussian_mean, latency_time_milliseconds()} |
       {time_gaussian_stddev, float()} |
       {time_absolute, latency_time_milliseconds()}) | system | false} |
 {monkey_chaos,
  list({probability_request, float()} |
       {probability_day, float()}) | system | false} |
 {dispatcher_pid_options,
  list({priority, low | normal | high} |
       {fullsweep_after, non_neg_integer()} |
       {min_heap_size, non_neg_integer()} |
       {min_bin_vheap_size, non_neg_integer()} |
       {max_heap_size, non_neg_integer() |
                       #{size => non_neg_integer(),
                         kill => boolean(),
                         error_logger => boolean()}} |
       {sensitive, boolean()} |
       {message_queue_data, off_heap | on_heap | mixed})} |
 {aspects_init_after, list(aspect_init_after_internal())} |
 {aspects_request_before, list(aspect_request_before_internal())} |
 {aspects_request_after, list(aspect_request_after_internal())} |
 {aspects_info_before, list(aspect_info_before_internal())} |
 {aspects_info_after, list(aspect_info_after_internal())} |
 {aspects_terminate_before, list(aspect_terminate_before_internal())} |
 {init_pid_options,
  list({priority, low | normal | high} |
       {fullsweep_after, non_neg_integer()} |
       {min_heap_size, non_neg_integer()} |
       {min_bin_vheap_size, non_neg_integer()} |
       {max_heap_size, non_neg_integer() |
                       #{size => non_neg_integer(),
                         kill => boolean(),
                         error_logger => boolean()}} |
       {sensitive, boolean()} |
       {message_queue_data, off_heap | on_heap | mixed})} |
 {request_pid_uses, infinity | pos_integer()} |
 {request_pid_options,
  list({priority, low | normal | high} |
       {fullsweep_after, non_neg_integer()} |
       {min_heap_size, non_neg_integer()} |
       {min_bin_vheap_size, non_neg_integer()} |
       {max_heap_size, non_neg_integer() |
                       #{size => non_neg_integer(),
                         kill => boolean(),
                         error_logger => boolean()}} |
       {sensitive, boolean()} |
       {message_queue_data, off_heap | on_heap | mixed})} |
 {info_pid_uses, infinity | pos_integer()} |
 {info_pid_options,
  list({priority, low | normal | high} |
       {fullsweep_after, non_neg_integer()} |
       {min_heap_size, non_neg_integer()} |
       {min_bin_vheap_size, non_neg_integer()} |
       {max_heap_size, non_neg_integer() |
                       #{size => non_neg_integer(),
                         kill => boolean(),
                         error_logger => boolean()}} |
       {sensitive, boolean()} |
       {message_queue_data, off_heap | on_heap | mixed})} |
 {hibernate,
  list({period, period_seconds()} |
       {rate_request_min, number()}) | boolean()} |
 {reload, boolean()}]

% external service configuration options that are updatable
[{priority_default, ?PRIORITY_HIGH..?PRIORITY_LOW} |
 {queue_limit, undefined | non_neg_integer()} |
 {queue_size, undefined | pos_integer()} |
 {rate_request_max,
  list({period, period_seconds()} |
       {value, number()}) | number() | undefined} |
 {dest_refresh_start, dest_refresh_delay_milliseconds()} |
 {dest_refresh_delay, dest_refresh_delay_milliseconds()} |
 {request_name_lookup, sync | async} |
 {request_timeout_adjustment, boolean()} |
 {request_timeout_immediate_max,
  request_timeout_immediate_max_milliseconds()} |
 {response_timeout_adjustment, boolean()} |
 {response_timeout_immediate_max,
  response_timeout_immediate_max_milliseconds()} |
 {monkey_latency,
  list({time_uniform_min, latency_time_milliseconds()} |
       {time_uniform_max, latency_time_milliseconds()} |
       {time_gaussian_mean, latency_time_milliseconds()} |
       {time_gaussian_stddev, float()} |
       {time_absolute, latency_time_milliseconds()}) | system | false} |
 {monkey_chaos,
  list({probability_request, float()} |
       {probability_day, float()}) | system | false} |
 {dispatcher_pid_options,
  list({priority, low | normal | high} |
       {fullsweep_after, non_neg_integer()} |
       {min_heap_size, non_neg_integer()} |
       {min_bin_vheap_size, non_neg_integer()} |
       {max_heap_size, non_neg_integer() |
                       #{size => non_neg_integer(),
                         kill => boolean(),
                         error_logger => boolean()}} |
       {sensitive, boolean()} |
       {message_queue_data, off_heap | on_heap | mixed})} |
 {aspects_init_after, list(aspect_init_after_external())} |
 {aspects_request_before, list(aspect_request_before_external())} |
 {aspects_request_after, list(aspect_request_after_external())} |
 {aspects_terminate_before, list(aspect_terminate_before_external())} |
 {limit, limit_external()}]

2.10 - services

curl http://localhost:6464/cloudi/api/rpc/services.erl

List the service configuration parameters with each service's UUID. Any default settings are ignored to keep the output concise.

2.11 - nodes_set

curl -X POST -d "[{reconnect_delay, 300}]" http://localhost:6464/cloudi/api/rpc/nodes_set.erl

Set the node configuration to specify how CloudI node connections are handled (using distributed Erlang).

discovery:

multicast:

ec2:

EC2 auto-discovery configuration requires setting 'access_key_id' and 'secret_access_key' with either 'groups' and/or 'tags'. Both 'groups' and 'tags' allow boolean expressions with nesting (specified as a list), e.g.:

[TAG | GROUP | OPERATOR]                 % implicitly an OR relationship
{'OR', [TAG | GROUP | OPERATOR]}         % OR boolean OPERATOR
{'AND', [TAG | GROUP | OPERATOR]}        % AND boolean OPERATOR

"security-group-name"                    % GROUP

"key1" | ["key3", "key4"]                % TAG (key names)

{"key2", "value2"} |                     % TAG (key/value combinations)
{["key5", "key6"], "value5"} |           %
{"key5", ["value5", "value6"]} |         %
{["key5", "key6"], ["value5", "value6"]} %

% groups example #1 (implicit OR relationship):
["security-group-a", "security-group-b"]

% groups example #2 (explicit AND relationship):
[{'AND', ["security-group-a", "security-group-b"]}]

% groups example #3 (explicit OR relationship, same functionally as #1):
[{'OR', ["security-group-a", "security-group-b"]}]

% tags example
[{'AND', [{"deployment", "development"}, {"cluster", "project42"}]}]

The EC2 auto-discovery requires that the security group(s) used by the instances expose distributed Erlang ports (with TCP rules):

• port 4369 (epmd) 10.0.0.0/8
• ports 4374-4474 (inet_dist_listen) 10.0.0.0/8

2.12 - nodes_get

curl http://localhost:6464/cloudi/api/rpc/nodes_get.erl

List the current nodes configuration in the same format provided to nodes_set with default settings ignored to keep the output concise.

2.13 - nodes_add

curl -X POST -d "['cloud001@cluster1']" http://localhost:6464/cloudi/api/rpc/nodes_add.erl

Explicitly add a CloudI node name, so that services between all other CloudI nodes and the added nodes can send each other service requests.

2.14 - nodes_remove

curl -X POST -d "['cloud001@cluster1']" http://localhost:6464/cloudi/api/rpc/nodes_remove.erl

Explicitly remove a CloudI node name. The CloudI node must have been added explicitly to be removed explicitly (not added by an auto-discovery method).

2.15 - nodes_alive

curl http://localhost:6464/cloudi/api/rpc/nodes_alive.erl

List all the CloudI nodes known to be connected.

2.16 - nodes_dead

curl http://localhost:6464/cloudi/api/rpc/nodes_dead.erl

List all the CloudI nodes that are disconnected but expected to reconnect.

2.17 - nodes

curl http://localhost:6464/cloudi/api/rpc/nodes.erl

List both the connected and disconnected CloudI nodes.

2.18 - logging_set

curl -X POST -d '[{file, undefined}, {syslog, []}]' http://localhost:6464/cloudi/api/rpc/logging_set.erl

Set the logging configuration for a CloudI node.

% logging configuration options
[{file, undefined | string()},                % defaults to "logs/cloudi.log"
 {level, off | fatal | error |
         warn | info | debug | trace},        % defaults to trace
 {redirect, undefined | node()},              % defaults to undefined
 {syslog, undefined | list()},                % defaults to undefined
 {formatters, undefined | list()},            % defaults to undefined
 {aspects_log_before,
  list(aspects_log_before())},                % defaults to []
 {aspects_log_after,
  list(aspects_log_after())}]                 % defaults to []

aspects_log_before:

Provide a list of functions with the type signature shown below, with each function as either an anonymous Erlang function or an Erlang tuple "{module(), FunctionName :: atom()}". Each function will be called before the log data is stored to disk.

fun((Level :: fatal | error | warn | info | debug | trace,
     Timestamp :: erlang:timestamp(),
     Node :: node(),
     Pid :: pid(),
     Module :: module(),
     Line :: pos_integer(),
     Function :: atom() | undefined,
     Arity :: arity() | undefined,
     MetaData :: list({atom(), any()}),
     LogMessage :: string()) ->
    ok.

aspects_log_after:

Provide a list of functions with the type signature shown below, with each function as either an anonymous Erlang function or an Erlang tuple "{module(), FunctionName :: atom()}". Each function will be called after the log data is stored to disk.

fun((Level :: fatal | error | warn | info | debug | trace,
     Timestamp :: erlang:timestamp(),
     Node :: node(),
     Pid :: pid(),
     Module :: module(),
     Line :: pos_integer(),
     Function :: atom() | undefined,
     Arity :: arity() | undefined,
     MetaData :: list({atom(), any()}),
     LogMessage :: string()) ->
    ok.

2.19 - logging_file_set

curl -X POST -d '"logs/cloudi_rotated.log"' http://localhost:6464/cloudi/api/rpc/logging_file_set.erl

Set the file path for logging output. If set to 'undefined', logging output will only be sent to syslog and formatters with an output module.

2.20 - logging_level_set

curl -X POST -d 'warn' http://localhost:6464/cloudi/api/rpc/logging_level_set.erl

Modify the loglevel. The loglevel is changed with an Erlang module update internally so any logging statements that are turned off create no latency. If set to 'undefined' or 'off', logging output will only be sent to syslog and formatters with an output module. The available log levels values are: off, fatal, error, warn, info, debug, trace.

2.21 - logging_syslog_set

curl -X POST -d '[{identity, "CloudI"}, {facility, local0}, {level, trace}]' http://localhost:6464/cloudi/api/rpc/logging_syslog_set.erl

Send all logging output to syslog.

2.22 - logging_formatters_set

curl -X POST -d '[{any, [{output, lager_file_backend}, {output_args, [{file, "logs/lager.log"}]}, {formatter, lager_default_formatter}, {level, trace}]}]' http://localhost:6464/cloudi/api/rpc/logging_formatters_set.erl

Provide integration with lager-compatible formatters and lager-compatible backends. Each formatter entry specifies a list of modules for the source of the logging output to match against paired with formatter options (e.g., {[module1, module2], Options}). A separate formatter entry with an 'any' atom instead of a list of modules is used if the source of the logging output is not provided (e.g., {any, Options}). Use 'STDOUT' and 'STDERR' as a module name entry to control the stdout and stderr output coming from external services (logging output for both streams provides the OS pid next to the stream name, instead of a module line number). If only a formatter is specified (i.e., without an output module, a lager-compatible backend), the formatter transforms the logging output to be logged to the CloudI log file and/or syslog. If an output module is provided (that implements the gen_event Erlang/OTP behaviour), it will consume the logging output separately from the CloudI log file and syslog.

2.23 - logging_redirect_set

curl -X POST -d 'cloudi@host' http://localhost:6464/cloudi/api/rpc/logging_redirect_set.erl

Redirect all local log output to a remote CloudI node. Use 'undefined' as the node name to log locally.

2.24 - logging

curl http://localhost:6464/cloudi/api/rpc/logging.erl

List the current logging configuration in the same format provided to the configuration file with default settings ignored to keep the output concise.

2.25 - code_path_add

curl -X POST -d '"/home/user/code/services"' http://localhost:6464/cloudi/api/rpc/code_path_add.erl

Add a directory to the CloudI Erlang VM code server's search paths. The path is always appended to the list of search paths (you should not need to rely on search path order because of unique naming).

2.26 - code_path_remove

curl -X POST -d '"/home/user/code/services"' http://localhost:6464/cloudi/api/rpc/code_path_remove.erl

Remove a directory from the CloudI Erlang VM code server's search paths. This doesn't impact any running services, only services that will be started in the future.

2.27 - code_path

curl http://localhost:6464/cloudi/api/rpc/code_path.erl

List all the CloudI Erlang VM code server search paths (in the same order the directories are searched).