[sr-dev] git:master: dmq: regenerated readme
Charles Chance
charles.chance at sipcentric.com
Mon Sep 16 00:43:25 CEST 2013
Module: sip-router
Branch: master
Commit: 923d09f0c1ece04c8d3c2755b5b201b3a2cd2deb
URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=923d09f0c1ece04c8d3c2755b5b201b3a2cd2deb
Author: Charles Chance <charles.chance at sipcentric.com>
Committer: Charles Chance <charles.chance at 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.
+...
More information about the sr-dev
mailing list