Communication Ring

Availability  LightWave® 8.0
Component  Layout, Modeler
Header  lwcomring.h

The Communication Ring provides a mechanism that allows plug-ins to notify other plug-ins of events.  The "ring" nature of the mechanism allows any plug-in to create a "ring" and any other plug-in to "subscribe" to events on that ring.  Any member of the ring can generate events on the ring, and all members on the ring will receive the event.  Each event will include an event code, and a pointer that can optionally contain data associated with the event.

As events are generated, each subscriber on the ring (except for the event owner) is notified to process the event.  This notification takes place in real-time, so processing of each event should take place as quickly as possible to avoid noticeable delays in the main application.

A ring is destroyed when the last subscriber detaches from it. 

Global Call

   LWComRing *cmFunc;
   cmFunc = global( LWCOMRING_GLOBAL, GFUSE_TRANSIENT );

The global function returns a pointer to an LWComRing structure.

    typedef struct st_LWComRing {
        int     (*ringAttach)(char *topic,LWInstance pidata,RingEvent eventCallback);
        void    (*ringDetach)(char *topic,LWInstance pidata);
        void    (*ringMessage)(char *topic,int eventCode,void *eventData);
    } LWComRing;

Event Support

Each subscriber to a ring uses the ringAttach() function to register their subscription.  Each ring has a unique topic, which is simply a string that distinguishes that particular communication ring from any others.  In addition, you provide a pointer to some unique data to identify your particular subscription on the ring.  Because you might have multiple instances of a single plug-in subscribed to a single ring, it would be a good idea to use your plug-in's instance data pointer as this argument.

When attaching to (or creating) a ring, you must provide a pointer to a callback function that will be invoked whenever an event occurs on that ring.  The function has the following prototype:

    typedef void (*RingEvent)(void *clientData,void *portData,int code,void *data);

The clientData pointer is the one provided to the ringAttach() function when the you subscribe to a ring.  The code value is a user-defined code for the event, and data is a pointer to any data associated with the event (it may be NULL if the event includes no data).

The portData pointer is only used internally, and currently has no useful purpose for a ring client.

Exported ComRing Functions

success = ringAttach( topic, id, callback )

Register a subscription with a Communication Ring.  The topic should be unique among Communication Rings, and the id should be unique among instances of your plug-in.  The callback pointer is where your plug-in will be called when events occur on the ring.  A return value of one (1) indicates a successful subscription, while zero (0) indicates an error of some kind occurred.

ringDetach( topic, id )

When a plug-in is finished using a Communication Ring, it needs to detach from it.  topic and id should be the same values used when you subscribed to the ring.

ringMessage( topic, code, data )

This function generates an event on the ring specified by topic.  The event code is an integer value whose value is completely user-defined.  The data pointer should be set to NULL if the event being generated contains no data, or can be a pointer to any kind of data that should be provided to other plug-ins when their Communication Ring event callback is invoked.

 

Example

The ComRing SDK example project illustrates the usage of the Communication Ring system by allowing a Master LScript to control the appearance of a CustomObject plug-in in real-time.