Module: sip-router Branch: master Commit: 923d09f0c1ece04c8d3c2755b5b201b3a2cd2deb URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=923d09f… Author: Charles Chance <charles.chance(a)sipcentric.com> Committer: Charles Chance <charles.chance(a)sipcentric.com> Date: Sun Sep 15 23:38:45 2013 +0100 dmq: regenerated readme --- modules/dmq/README | 212 ++++++++++++++++++++++++++++++++++++++++++--------- 1 files changed, 174 insertions(+), 38 deletions(-) diff --git a/modules/dmq/README b/modules/dmq/README index cd6a3ce..d5de540 100644 --- a/modules/dmq/README +++ b/modules/dmq/README @@ -2,11 +2,21 @@ Distributed Message Queue Module Marius Ovidiu Bucur +Charles Chance + + Sipcentric Ltd. + Edited by Marius Ovidiu Bucur - Copyright � 2011 Marius Bucur +Edited by + +Charles Chance + + Copyright © 2011 Marius Bucur + + Copyright © 2013 Charles Chance, Sipcentric Ltd. __________________________________________________________________ Table of Contents @@ -21,18 +31,38 @@ Marius Ovidiu Bucur 3. Parameters - 3.1. dmq_server_address(str) - 3.2. dmq_notification_address(str) + 3.1. server_address(str) + 3.2. notification_address(str) + 3.3. num_workers(int) + 3.4. ping_interval(int) + + 4. Functions + + 4.1. dmq_handle_message() + 4.2. dmq_send_message(peer, node, body) 2. Developer Guide 1. dmq_load_api(dmq_api_t* api) + 2. register_dmq_peer(dmq_peer_t* peer) + 3. bcast_message(dmq_peer_t* peer, str* body, dmq_node_t* except, + dmq_resp_cback_t* resp_cback, int max_forwards) + + 4. send_message(dmq_peer_t* peer, str* body, dmq_node_t* node, + dmq_resp_cback_t* resp_cback, int max_forwards) List of Examples - 1.1. Set dmq_server_address parameter - 1.2. Set dmq_notification_address parameter + 1.1. Set server_address parameter + 1.2. Set notification_address parameter + 1.3. Set num_workers parameter + 1.4. Set ping_interval parameter + 1.5. dmq_handle_message usage + 1.6. dmq_send_message usage 2.1. dmq_api_t structure + 2.2. register_dmq_peer usage + 2.3. bcast_message usage + 2.4. send_message usage Chapter 1. Admin Guide @@ -46,17 +76,31 @@ Chapter 1. Admin Guide 3. Parameters - 3.1. dmq_server_address(str) - 3.2. dmq_notification_address(str) + 3.1. server_address(str) + 3.2. notification_address(str) + 3.3. num_workers(int) + 3.4. ping_interval(int) + + 4. Functions + + 4.1. dmq_handle_message() + 4.2. dmq_send_message(peer, node, body) 1. Overview - The DMQ module implements a distributed message passing system on top - of Kamailio. The DMQ nodes within the system are grouped in a logical - entity called DMQ bus and are able to communicate with each others by - sending/receiving messages (either by broadcast or sending a DMQ - message to a specific node). The system transparently deals with node - discovery, node consistency within the DMQ bus, retransmissions, etc. + The DMQ module implements a distributed message queue on top of + Kamailio in order to enable the passing/replication of data between + multiple instances. The DMQ "nodes" within the system are grouped in a + logical entity called the DMQ "bus" and are able to communicate with + each other by sending/receiving messages (either by broadcast or + directly to a specific node). The system transparently deals with node + discovery, consistency, retransmissions, etc. + + Other entities ("peers") are then able to utlize the DMQ bus to pass + messages between themselves. Peers are grouped by name in order to + ensure the correct messages are passed to the relevant peers. This + grouping of peers can be compared to a topic in a typical pub/sub + system. 2. Dependencies @@ -71,40 +115,99 @@ Chapter 1. Admin Guide 2.2. External Libraries or Applications - * Each peer needs to use its own serialization mechanism. Some + * The DMQ module itself has no external dependencies. However, each + peer will need to use its own (de)serialization mechanism. Some examples are libtpl, protobuf. . 3. Parameters - 3.1. dmq_server_address(str) - 3.2. dmq_notification_address(str) + 3.1. server_address(str) + 3.2. notification_address(str) + 3.3. num_workers(int) + 3.4. ping_interval(int) + +3.1. server_address(str) + + The local server address. This is the interface over which the DMQ + engine will send/receive messages. + + Default value is “NULL”. + + Example 1.1. Set server_address parameter +... +modparam("dmq", "server_address", "sip:10.0.0.20:5060") +... + +3.2. notification_address(str) + + The address of another DMQ node from which the local node should + retrieve initial information about all other nodes. + + Default value is “NULL”. + + Example 1.2. Set notification_address parameter +... +modparam("dmq", "notification_address", "sip:10.0.0.21:5060") +... + +3.3. num_workers(int) + + The number of worker threads for sending/receiving messages. + + Default value is “2”. -3.1. dmq_server_address(str) + Example 1.3. Set num_workers parameter +... +modparam("dmq", "num_threads", 4) +... + +3.4. ping_interval(int) + + The number of seconds between node pings (for checking status of other + nodes). + + Minimum value is “60” (default). + + Example 1.4. Set ping_interval parameter +... +modparam("dmq", "ping_interval", 90) +... + +4. Functions - The local server address. + 4.1. dmq_handle_message() + 4.2. dmq_send_message(peer, node, body) - The modules needs it to know on which interface the DMQ engine should - send and receive messages. +4.1. dmq_handle_message() - Default value is "NULL". + Handles a DMQ message by passing it to the appropriate local peer + (module). The peer is identified by the user part of the To header. - Example 1.1. Set dmq_server_address parameter + This function can be used from REQUEST_ROUTE. + + Example 1.5. dmq_handle_message usage ... -modparam("dmq", "dmq_server_address", "mysql://openser:openserrw@localhost/opens -er") + if(is_method("KDMQ")) + { + dmq_handle_message(); + } ... -3.2. dmq_notification_address(str) +4.2. dmq_send_message(peer, node, body) + + Sends a DMQ message directly from config file. - The address of the DMQ node from which the local node should retrieve - initial information. + Meaning of parameters: + * peer - name of peer that should handle the message. + * node - the node to which the message should be sent. + * body - the message body. - Default value is "NULL". + This function can be used from any route. - Example 1.2. Set dmq_notification_address parameter + Example 1.6. dmq_send_message usage ... -modparam("dmq", "dmq_notification_address", "mysql://openser:openserrw@localhost -/openser") + dmq_send_message("peer_name", "sip:10.0.0.21:5060", "Message body...\n") +; ... Chapter 2. Developer Guide @@ -112,18 +215,20 @@ Chapter 2. Developer Guide Table of Contents 1. dmq_load_api(dmq_api_t* api) + 2. register_dmq_peer(dmq_peer_t* peer) + 3. bcast_message(dmq_peer_t* peer, str* body, dmq_node_t* except, + dmq_resp_cback_t* resp_cback, int max_forwards) + + 4. send_message(dmq_peer_t* peer, str* body, dmq_node_t* node, + dmq_resp_cback_t* resp_cback, int max_forwards) The module provides the following functions that can be used in other Kamailio modules. -1. dmq_load_api(dmq_api_t* api) +1. dmq_load_api(dmq_api_t* api) - This function binds the dmq modules and fills the structure with the - exported functions -> register_dmq_peer - registers an entity as a DMQ - peer which permits receiving/sending messages between nodes which - support the same peer, -> bcast_message - broadcast a DMQ message to - all peers available in the DMQ bus, -> send_message - sends a DMQ - message to a specific peer in the local DMQ bus. + This function binds the DMQ module and fills the structure with the + exported functions below. Example 2.1. dmq_api_t structure ... @@ -133,3 +238,34 @@ typedef struct dmq_api { send_message_t send_message; } dmq_api_t; ... + +2. register_dmq_peer(dmq_peer_t* peer) + + Registers an entity as a DMQ peer which permits receiving/sending + messages between nodes which support the same peer. + + Example 2.2. register_dmq_peer usage +... + Example to follow. +... + +3. bcast_message(dmq_peer_t* peer, str* body, dmq_node_t* except, +dmq_resp_cback_t* resp_cback, int max_forwards) + + Broadcast a DMQ message to all nodes in the DMQ bus excluding self, + inactive nodes and "except" if specified. + + Example 2.3. bcast_message usage +... + Example to follow. +... + +4. send_message(dmq_peer_t* peer, str* body, dmq_node_t* node, +dmq_resp_cback_t* resp_cback, int max_forwards) + + Send a DMQ message to a single node. + + Example 2.4. send_message usage +... + Example to follow. +...