Free High Performance CORBA Notification Service from AT&T Laboratories

omniORB Home AT&T Research

Back to Documentation Home Page

Developing Push Suppliers

This section goes over the details of the StructuredPushSupplier_i class found in sample_clients.h / sample_clients.cc.  This class does all the real work of the example program struct_push_supplier.cc.  (As discussed in the Common Code section, the main program creates a StructuredPushSupplier_i object using the class's create function, tells the new client object to connect to its proxy using the connect method, and then waits for the desired number of events to be supplied using the wait_done method.)

This section assumes you have read the section covering class StructuredPushConsumer_i. All the client code has the same basic structure, so we do not repeat things here that are covered in that section.

The rest of this section covers the class declaration (in sample_clients.h) and the class implementation (in sample_clients.cc).

Class Declaration (sample_clients.h)

Here is the beginning of the class declaration:

A push supplier of structured events must implement the CosNotifyComm::StructuredPushSupplier interface.  Thus, class StructuredPushSupplier_i inherits from the POA skeleton class POA_CosNotifyComm::StructuredPushSupplier.  It also inherits from the ``mix-in'' class PortableServer::RefCountServantBase to enable automatic object disposal based on reference counting: the POA will destroy the object when its reference count reaches zero. Finally, the class inherits from class GenericWorker. GenericWorker is defined at the top of sample_clients.h. Any class that inherits from GenericWorker must implement the start_working method, which will run in its own thread. As we'll see below, start_working will be used to push events to the notification channel.

The constructor, create function, and most of the methods are the same as in the declaration for StructuredPushConsumer_i, with these exceptions.  First, _my_proxy has type CosNA_StructuredProxyPushConsumer_var (a structured push supplier must connect to a structured proxy push consumer). Second, rather than having an offer_change method, suppliers have a subscription_change method. (The default change function for all suppliers is sample_subscription_change_fn.) Third, the create call takes a function used for supplying structured events, instead of a function for consuming events. The default supply function is sample_supply_structured_fn, and is found in sample_functions.cc. Finally, there is no push method. A push supplier does not have a method related to pushing. The proxy provides the method push_structured_event to support pushing of events to the channel.

The following is the complete class declaration.

Class Implementation (sample_clients.cc)

The push supplier classes are very similar in structure to the pull consumer classes -- both use a worker thread to either pull events from the channel or push events to the channel.  For this class, events are pushed using the proxy's push_structured_event method.  The supplier performs this call in a worker thread, pausing for _millisecs milliseconds between each push call.  (A setting of zero means push as fast as possible.)  Because this worker thread is constantly communicating with the channel, there is no need for a separate 'ping thread' to monitor the liveness of the proxy.

Start_working Method

As with the pull consumer, the key method is the start_working method:

start_working enters a while loop, while(1), which loops until a break statement is executed.   At the top of the loop, _oplock is always held.  Each time through the loop, the lock is released, push_structured_event is called, then the lock is reacquired.  As with a ping loop, it is important to release the lock across a call to a remote object so that other methods can execute during this call.  

There are three things that cause a break from the while loop:  _done has been set to 1 by another method (such as disconnect_structured_push_supplier); the target event count is reached; an error occurs during a push call.  For the latter 2 cases, the code following the while loop will set _done to true and signal the _finish condition variable using broadcast.   This will wake any thread waiting on that condition (see wait_done).   For the case where an error occurs during a push call, _com_err is set to true before executing the break statement.

Prior to performing a push, the _consume_fn is used to obtain the structured event to be pushed to the channel.  (The default function, sample_push_structured_fn, provides events of type Stock::Ticker and Bond::Ticker with stock and bond price quotes.  See sample_functions.cc.)  The function need not return an event; if it does not, the push call is skipped and the loop continues (after yielding or waiting, as discussed below).  For each successful push, the method  increments the count of the number of events received, _num_events.  If _num_events has reached _max_events, a break occurs.  

At the bottom of the while loop, if _millisecs is zero then omni_thread::yield() is called, otherwise timewait is called with the specified number of milliseconds (converted to an absolute seconds/nanoseconds time value).  The yield is done to ensure that the thread running the start_working method does not 'hog' the processor... it gives other methods that need _oplock a chance to run.  (Since start_working releases the lock on each push, the yield call may not be strictly necessary.)

Complete Implementation Listing

The complete listing of the class implementation is presented below.

Back to Documentation Home Page