CascadeWormhole Class Reference

easy to use high performance inter-process communication mechanism More...

#include <cascade/interprocess/CascadeWormhole.h>

Inheritance diagram for CascadeWormhole:

List of all members.

Public Types
typedef bool()	WormholeEnumProc (const char *pWormholeURL, void *pClientData)
enum	{ kMaxName = 96, kMaxNameLen = kMaxName - 1 }
Public Member Functions
	CascadeWormhole ()
virtual	~CascadeWormhole ()
bool	Create (const char *pWormholeURL)
void	Destroy ()
CascadeMessage *	WaitForMessage (u32 nTimeoutMilliseconds=0)
bool	PostMessage (const char *pWormholeURL, u32 nMessageID, void *pMessageData=NULL, u32 nDataSize=0)
bool	BroadcastMessage (const char *pBroadcastURL, u32 nMessageID, void *pMessageData=NULL, u32 nDataSize=0)
bool	SendMessage (const char *pWormholeURL, u32 nMessageID, void *pMessageData, u32 nDataSize, CascadeMessage *&pReplyMessageToSet)
bool	SendReply (u32 nReplyMessageID, void *pMessageData=NULL, u32 nDataSize=0)
Static Public Member Functions
static bool	EnumerateWormholes (const char *pWormholeURL, WormholeEnumProc *pEnumProc, void *pClientData)
static bool	DoesWormholeExist (const char *pWormholeURL)

---

Detailed Description

easy to use high performance inter-process communication mechanism

Skip the description

CascadeWormhole is the Cascade mechanism for inter-process communication. Wormholes provide the ability to transfer anything from small messages to huge media streams in a super-duper-high- performance manner between threads of a same process, threads of different processes, even threads of different processes on different machines.

Wormhole (n)
    1 : a hole or passage burrowed by a worm
    2 : a hypothetical structure of space-time envisioned as a long thin tunnel
        connecting points that are separated in space and time
    3 : a Cascade data-structure and run-time facility envisioned as a long thin tunnel
        connecting threads within and across processes and machines with multiple entry
        points for parcels of data sent through the Wormhole

Wormholes are identified by their URLs. All wormholes on the same host have unique names and are referred to as "wormhole://localhost/" based URLs. "wormhole://localhost/" based URLs are the only URLs supported in the 1.0 implementation of this interface. The unique part of the wormhole name is the part to the right of the "wormhole://localhost/". This name is limited to a length of kMaxNameLen characters. kMaxName refers to the size of buffer needed to store string of kMaxNameLen.

See also:

kMaxName, kMaxNameLen

Before a wormhole can be used, it must be created with a call to Create(). Create() takes as its argument a string which is the URL of the wormhole to be created. This URL must start with "wormhole://localhost/" and must be unique. Both sender and receiver wormholes must have been created with unique URLs. Sending a wormhole message to yourself is illegal (send is synchronous), but posting a message to yourself is permitted. In order to minimize collisions in the namespace of wormhole URLs it is recommended that you create wormhole urls that contain your internet domain in them, as is the style in java class naming.
Example URLs:

    "wormhole://localhost/org.woodward.dons_application"
    "wormhole://localhost/com.ficticiouscompany.special.daemonwormhole"
    "wormhole://localhost/com.roku.cascade.cascadeprivate.internalwormhole"

See also:

Create()

Sending Wormhole Messages

Once your wormhole is created, you may immediately use it to send, post, or broadcast wormhole messages. Send a message by calling Send(). Send performs a synchronous send to the target wormhole and waits for a reply. The Send() function only returns to the caller when either (a) the reply has been received, or (b) a send error occurs. Once Send() has delivered the message to its target, it will block until either a reply is received or the target wormhole's process goes away (reply timeouts are not yet implemented). Post() is like Send() except that it is asyncrhonous. The message is posted to the target wormhole and no reply is expected. Flow of control returns to the caller as soon as the post is executed. Broadcast() broadcasts (via post) a copy of the message to every wormhole whose URL is a super-string of the broadcast URL. So for example, to broadcast a message to all wormholes on the localhost, one would use the broadcast URL: "wormhole://localhost/". To broadcast a message to all wormholes created by processes written by ficticious company, one would use the broadcast URL" "wormhole://localhost/com.ficticiouscompany".
Success and Failure
On success, Send(), Post() and Broadcast() return true; on failure they return false. A Send() or Post() will fail if the target wormhole doesn't exist or if the target wormhole's queues are full. This is one reason why it is always important for clients to always call WaitForMessage() in a loop! See: Receiving Wormhole Messages.
Alternatively, you can create an output only wormhole that will never accept messages.

See also:

Special "_outputonly:" Wormholes

Receiving Wormhole Messages

Once a wormhole is created, you may receive messages from it by calling WaitForMessage(). Even if you are not explicitly expecting messages to be arrive at to your wormhole they probably will, as other clients in the system are broadcasting (what hopefully are universally useful and infrequent) CascadeMessages to "wormhole://localhost/". So it is important to periodically call WaitForMessage() in a loop as in the following example:

    CascadeWormhole wormhole;
    CascadeMessage * pMessage = NULL;
    if (wormhole.Create("wormhole://localhost/com.yourcompany.here.yourwormholename"))
    {
        while (1)
        {
             pMessage = WaitForMessage();
             if (NULL == pMessage)
             {
                 // receive failure - probable SIGINT sent to my process
                 // I can break or continue as is my preference
                 break;
             }
             /* Do something with pMessage */
             /* break out of the loop when I've decided I'm done with this wormhole */
        }
        wormhole.Destroy();
    }

If you are receiving a message that was sent to you (check this with pMessage->IsReplyRequired()) then the sender is waiting on your reply. It is very important to reply in a timely fashion so as not to make the sender wait too long. Reply to a message with a call to SendReply(). If you start waiting for another message without sending a reply a default (empty) reply will be sent on your behalf.

Note:

If you only intend to send messages from your wormhole and never receive them you should create Special "_outputonly:" Wormholes

See also:

Create(), Destroy()

WaitForMessage(), SendReply()

CascadeMessage::WaitForMessage()

Special <code>"_outputonly:"</code> Wormholes

Sometimes it is desirable to create a wormhole for sending and not worry about having to receive messages on the wormhole. If this is your intent, you should create a special output only wormhole. This is done by pre-pending "_outputonly" to your wormhole name. For example "wormhole://localhost/_outputonly:com.ficticiouscompany.wormhole" is a URL for an output only wormhole. Output only wormholes may only call Send(), Post(), and Broadcast(). No wormhole messages will ever be received by an output only wormhole. Therefore, you never need to call WaitForMessage() on an output only wormhole.

Note:

FINAL NOTE:As previously mentioned, only localhost wormholes are currently supported. Furthermore, wormholes are implemented with SOCK_STREAM AF_UNIX local sockets. As a result, passing large data through a wormhole is better accomplished by passing the name and size parameters of a CascadeSharedMemZone through the wormhole. Then, the receiver of the wormhole message can use this information to open and maplock the SharedMemZone to access the large data.

See also:

CascadeSharedMemZone

---

class CascadeWormhole

---

Member Typedef Documentation

typedef bool() CascadeWormhole::WormholeEnumProc(const char *pWormholeURL, void *pClientData)

Callback function for enumerating wormholes on the local system Clients provide their own WormholeEnumProc to the EnumerateWormholes() function. Your custom WormholeEnumProc will get called back by the EnumerateWormholes() function, one for each wormhole that matches the matching criteria. Parameters: pWormholeURL  the URL of the wormhole pClientData  the void * pClientData passed thru from EnumerateWormholes() Returns: You should return true to continue enumeration, false to abort it Note: The pWormholeURL passed into your enum proc is only valid for the lifetime of the callback. So do not cache pWormholeURL pointers. Instead copy the strings if you want to remember them. See also: EnumerateWormholes()

---

Member Enumeration Documentation

anonymous enum

Enumeration values: kMaxName  the buffer size required to hold a wormhole URL kMaxNameLen  the maximum character length of a wormhole URL

---

Constructor & Destructor Documentation

CascadeWormhole::CascadeWormhole (   )

the default constructor - lightweight This default constructor is lightweight.

virtual CascadeWormhole::~CascadeWormhole (   )  [virtual]

destructor This destructor will Destroy() the wormhole if necessary. See also: Destroy()

---

Member Function Documentation

bool CascadeWormhole::BroadcastMessage (  const char *  pBroadcastURL, u32  nMessageID, void *  pMessageData = NULL, u32  nDataSize = 0 )

broadcasts a wormhole message asynchronously BroadcastMessage() will asynchronously broadcast the message identified by nMessageID to the wormhole destinations identified by pBroadcastURL. Each recipient receives a copy of the pMessageData. Each wormhole where pBroadcastURL is a substring of the wormhole's URL will receive the broadcasted message. Parameters: pBroadcastURL  the wormholeURL to broadcast the message to nMessageID  the messageID of the message to broadcast pMessageData  the message data to broadcast nDataSize  the size in bytes of the message data Returns: whether or not the broadcast succeeded See also: PostMessage(), SendMessage()

bool CascadeWormhole::Create (  const char *  pWormholeURL  )

creates a wormhole Create() creates the wormhole identified by pWormholeURL returning true if successful, false otherwise. pWormholeURL must refer to a local URL starting with "wormhole://localhost/" whose unique part of the URL has a string length of not more than kMaxNameLen. Parameters: pWormholeURL  the URL of the wormhole to create Returns: whether or not the creation succeeded See also: Destroy()

void CascadeWormhole::Destroy (   )

destroys the wormhole Destroy() destroys a previously created wormhole. Returns: whether or not the destroy succeeded See also: Destroy(), ~CascadeWormhole()

static bool CascadeWormhole::DoesWormholeExist (  const char *  pWormholeURL  )  [static]

determines whether or not a wormhole exists DoesWormholeExist() returns true if the wormhole identified by pWormholeURL currently exists, false otherwise. Parameters: pWormholeURL  the URL to test Returns: whether or not the wormhole exists

static bool CascadeWormhole::EnumerateWormholes (  const char *  pWormholeURL, WormholeEnumProc *  pEnumProc, void *  pClientData )  [static]

enumerates wormholes on the local system call EnumerateWormholes() to enumerate the wormholes that match on pWormholeURL. (Those wormholes where pWormholeURL is substring of their wormhole URL). If pWormholeURL is NULL or empty (""), then all local wormholes are enumerated. Parameters: pWormholeURL  the URL string or substring to match on pEnumProc  the wormhole enum proc pClientData  the void * pClientData passed straight through to your enum proc Returns: true if enumeration carried through to completion, false if it was aborted

bool CascadeWormhole::PostMessage (  const char *  pWormholeURL, u32  nMessageID, void *  pMessageData = NULL, u32  nDataSize = 0 )

posts a wormhole message asynchronously PostMessage() will asynchronously post the message identified by nMessageID to the wormhole identified by pWormholeURL returning true if successful, false otherwise. Parameters: pWormholeURL  the wormholeURL to post the message to nMessageID  the messageID of the message to post pMessageData  the message data to post nDataSize  the size in bytes of the message data Returns: whether or not the post succeeded See also: BroadcastMessage(), SendMessage()

bool CascadeWormhole::SendMessage (  const char *  pWormholeURL, u32  nMessageID, void *  pMessageData, u32  nDataSize, CascadeMessage *&  pReplyMessageToSet )

sends a wormhole message SendMessage() delivers the message identified by nMessageID to the wormhole identified by pWormholeURL synchronously. SendMessage() returns true if successful, false otherwise. SendMessage() sets pReplyMessageToSet (on success) with the reply message. See SendReply(). pReplyMessageToSet is only valid until the next call to SendMessage(). Parameters: pWormholeURL  the wormholeURL to send the message to nMessageID  the messageID of the message to send pMessageData  the message data to send nDataSize  the size in bytes of the message data pReplyMessageToSet  a pointer reference to a CascadeMessage that will point to the reply on successful return Returns: whether or not the send succeeded See also: PostMessage(), BroadcastMessage() SendReply()

bool CascadeWormhole::SendReply (  u32  nReplyMessageID, void *  pMessageData = NULL, u32  nDataSize = 0 )

sends a reply message SendReply() will send a reply to the most recently received synchronous message returning true if successful, false otherwise. SendReply() is only used to reply to messages sent to this wormhole with SendMessage(). That can be determined by calling pMessage->IsReplyRequired() on the message returned from WaitForMessage(). SendReply() sends a reply message with message id nMessageID, data pMessageData of size nDataSize to the wormhole that sent the message with SendMessage(). SendReply() returns true if successful, false otherwise. Note: The sending process will block until the receiving process calls SendReply() or until the receiving process waits for the next message (which does an implicit SendReply() with an internal AutoReply message with NULL data). Parameters: nReplyMessageID  the messageID of the reply message pMessageData  the message data to send nDataSize  the size in bytes of the message data Returns: whether or not the reply succeeded

CascadeMessage* CascadeWormhole::WaitForMessage (  u32  nTimeoutMilliseconds = 0  )

waits for a wormhole message WaitForMessage() blocks the calling thread for nTimeoutMilliseconds (0 == infinite) or until a CascadeMessage is received. WaitForMessage() returns non-null if successful, NULL if there is a timeout. The returned CascadeMessage * and the data it points to is valid until the next call to WaitForMessage(). Parameters: nTimeoutMilliseconds  the amount of milliseconds to wait before returning Returns: the CascadeMessage received from the wormhole or NULL on timeout or error See also: CascadeMessage

---

The documentation for this class was generated from the following file:

• CascadeWormhole.h

---