-
Notifications
You must be signed in to change notification settings - Fork 15
Cocaine Dealer API Reference
- C++
- Data Structures
- [message_path_t structure] (#mess-path)
- message_policy_t structure
- message_t structure
- data_container structure
- Python
The main header file — cocaine/dealer/dealer.hpp.
Dealer_t is responsible for sending and routing of the messages in the cloud. For these purposes it has the following set of methods.
Class methods:
| Method | Description |
|---|---|
| dealer_t | Creating an object. |
| send_message | Sending one message. |
| send_messages | Sending multiple messages. |
| policy_for_service | Working with the routing policy. |
| stored_messages_count | Working with the persistent queue. |
| remove_stored_message | Working with the persistent queue. |
| remove_stored_message_for | Working with the persistent queue. |
| get_stored_messages | Working with the persistent queue. |
Creating an object.
explicit dealer_t(const std::string& config_path = "");Accepts: path to the configuration file.
Returns: nothing.
Sending one message.
response_ptr_t send_message(const message_t& message);Accepts: message to send.
Returns: a pointer to an object of type response_t.
response_ptr_t send_message(const void* data,
size_t size,
const message_path_t& path,
const message_policy_t& policy);
response_ptr_t send_message(const void* data,
size_t size,
const message_path_t& path);
template <typename T> response_ptr_t send_message(const T& object,
const message_path_t& path,
const message_policy_t& policy)
template <typename T> response_ptr_t send_message(const T& object,
const message_path_t& path)Accepts:
- data - a pointer to the data of the message being sent;
- size - size of the data of the message being sent;
- path - the message path, i.e. the name of the method in a specific application in the cloud;
- object - any type of object that will be automatically serialized before sending;
- policy - routing policies for the message being sent.
Returns: a pointer to an object of type response_t.
You can send a single message to multiple applications simultaneously, by setting the regular expression in the path.service_alias. Returns a list of responses from each service to which the message was sent.
responses_list_t send_messages(const void* data,
size_t size,
const message_path_t& path,
const message_policy_t& policy);
responses_list_t send_messages(const void* data,
size_t size,
const message_path_t& path);Accepts:
- data - a pointer to the data of the message being sent;
- size - size of the data of the message being sent;
- path - the message path, i.e. the name of the method in a specific application in the cloud;
- policy - routing policies for the message being sent.
Returns: a pointer to an object of type response_t.
This method is used to obtain the standard routing policies for the desired application.
message_policy_t policy_for_service(const std::string& service_alias);Accepts:
- service_alias - application alias.
Returns: an object of message_policy_t type.
This method is used to obtain the number of cached message in the local message store for a particular application.
size_t stored_messages_count(const std::string& service_alias);Accepts:
- service_alias - application alias.
Returns: the number of cached messages for a given application.
This method removes a message from the local store.
void remove_stored_message(const message_t& message);Accepts:
- message - the message that should be removed.
Returns: nothing.
remove_stored_message_for method
This method removes the message from the local store for the appropriate response to this message.
void remove_stored_message_for(const response_ptr_t& response);Accepts:
- response - a pointer to the object response_t, the original message which must be removed.
Returns: nothing.
This method provides a list of messages that are cached in the local store for a certain application.
void get_stored_messages(const std::string& service_alias,
std::vector<message_t>& messages);Accepts:
- service_alias - alias of the application;
- messages - the list of cached messages.
Returns: nothing.
This object manages the receiving of the responses for the request. In order to get the data send as a response from the server you need to use the following method:
bool get(data_container* data, double timeout = -1.0d);Accepts:
- data - pointer to the structure data_container;
- timeout - the maximum time to wait for a response from the server (in seconds).
Returns: true, if we have not yet received the last chunk of the response and false in all other cases.
Header file — cocaine/dealer/message_path.hpp.
This structure fully describes the route of the message in the cloud. This structure describes what application and what method will be used to process your request.
struct message_path_t {
message_path_t() {};
message_path_t(const std::string& service_alias_,
const std::string& handle_name_) :
service_alias(service_alias_),
handle_name(handle_name_) {}
message_path_t(const message_path_t& path);
message_path_t& operator = (const message_path_t& rhs);
bool operator == (const message_path_t& mp) const;
bool operator != (const message_path_t& mp) const;
std::string as_string() const;
std::string service_alias;
std::string handle_name;
};Fields:
- service_alias (type std::string) - alias of the application (by default - an empty string);
- handle_name (type std::string) - method of the application (by default - an empty string).
Header file — cocaine/dealer/message_policy.hpp.
This structure describes the rules by which the message is sent to the cloud (the routing policy of the messages).
struct message_policy_t {
message_policy_t();
message_policy_t(bool urgent_,
bool persistent_,
float timeout_,
float deadline_,
int max_retries_) {};
message_policy_t(const message_policy_t& mp);
message_policy_t& operator = (const message_policy_t& rhs);
bool operator == (const message_policy_t& rhs) const;
bool operator != (const message_policy_t& rhs) const;
policy_t server_policy() const;
policy_t server_policy();
std::string as_string() const;
bool urgent;
bool persistent;
double timeout;
double deadline;
int max_retries;
};Fields:
- urgent (type bool) - priority flag, if set, the message is queued at head of the request queue (default - false);
- persistent (type bool) - flag, indicated the need of caching the messages to local disk storage (default - false);
- timeout (type double) - the time in seconds that describes the maximum time period for processing one chunk of data on the side of the application (by default - 0, ie unlimited time);
- deadline (type double) - the time in seconds, which describes the maximum length of the time over which the message should be handled entirely with all its chunks (default - 0, ie unlimited time);
- max_retries (type int) - maximum number of attempts, which the Cocaine Dealer should make in an effort to process your request, unless the processing has failed due to a critical error (by default - 0, i.e., when an error happens, the message is not being resent, also you can specify an unlimited number of times, by setting max_retries to -1).
Header file — cocaine/dealer/message.hpp.
This structure contains the data to send, track and delivery rules.
class message_t {
public:
message_t() {}
message_path_t path;
message_policy_t policy;
data_container data;
std::string id;
};Fields:
- data - the data being sent;
- path - the message route;
- policy - request routing policy.
Header file — cocaine/dealer/utils/data_container.hpp.
This structure is responsible for the storage of the binary data..
data_container();Accepts: nothing.
Returns: nothing.
data_container(const void* data, size_t size);Accepts:
- data - a pointer to the data;
- size - the size of the data.
Returns: nothing.
Method to obtain a pointer to the data stored in data_container.
void* data() const;Accepts: nothing.
Returns: a pointer to the data.
Method to get the size of data stored in data_container.
size_t size() const;Accepts: nothing.
Returns: the size of the data.
Method to check if the object is void.
bool empty() const;Accepts: nothing.
Returns: true, if the object is empty and false otherwise.
Method, which removes the data stored in the object.
void clear();Accepts: nothing.
Returns: nothing.
Method, which assigns the data object.
void set_data(const void* data, size_t size);Accepts:
- data - a pointer to the data;
- size - the size of the data.
Returns: nothing.
Package: cocaine.client.
Designer:
Client(config_path)An example:
from cocaine.client import Client
c = Client("/etc/cocaine/dealer.conf")Accepts: path to the configuration file.
Returns: nothing.
send(path, message = None, **kwargs)An example:
path = "my_application/very_important_event"
response = c.send(path, {"my_data": [3.14, 42, "Hello, World!"]}, timeout = 2.5, max_retries = 3)Accepts:
- path - the path, as a string, in the following format: “application_name/event_name”;
- message - the message (if the object passed to the message supports the buffer protocol, it will
- be sent as is, if not - the library will attempt to serialize it by the means of MessagePack library.
Optional arguments:
- urgent (type bool) - priority flag (default - false);
- timeout (type double) - time limit (in seconds) to process a single chunk of data on the side of the application (by default - 0, ie unlimited time);
- deadline (type double) - time limit (in seconds) to process the whole message with all its chunks (default - 0, ie unlimited time);
- max_retries (type int) - maximum number of attempts, which the Cocaine Dealer should make in an effort to process your request, unless the processing has failed due to a critical error (by default - 0, i.e., when an error happens, the message is not being resent, also you can specify an unlimited number of times, by setting max_retries to -1).
Returns: an object of Response class.
get(path, message = None, **kwargs)An example:
path = "my_application/another_event"
chunk_one, chunk_two = c.get(path, {"user_id": 100500}, deadline = 5.0)A wrapper for the send method, which collects all of the response chunks and returns them in a list.
This class is used to receive the response chunks for the sent message. This class cannot be created by yourself.
get(timeout = -1.0)Waits for the next part of the response within the specified time, and returns it as a string. If the timeout is -1, this call will block infinitely. If timeout is 0, this method willl only check whether there is a ready answer: If yes - it will be returned as a string, if not - return immediately.
An example:
path = "my_application/process_stream"
response = c.send(path, {"stream_id": 42})
chunk = response.get(timeout = 1.5)Class Response is an iterable object.
An example:
path = "my_application/process_stream"
response = c.send(path, {"stream_id": 42})
for chunk in response:
print str(chunk)