Module: sip-router Branch: master Commit: 923d09f0c1ece04c8d3c2755b5b201b3a2cd2deb URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=923d09f0...
Author: Charles Chance charles.chance@sipcentric.com Committer: Charles Chance charles.chance@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. +...