7.4 Polling

   There are two types of Polling model invocations that allow a client to proceed before the request finishes: The DII’s send (which supports deferred synchronous invocations) and the typed sendp variants of the interface stubs (which support both deferred synchronous and asynchronous invocations). This section describes a single mechanism that allows a client to query or block on the completion of outstanding requests.

• A client might want to mix deferred typed and dynamic operations. Deferred DII (in some unholy combination of language mappings) has operations somewhat similar to those of the typed Poller: ORB::poll_next_response and ORB::get_next_response. It should be possible to mix the two kinds of polling: typed and dynamic.

• Other potential happenings might occur that are susceptible to polling in current or future CORBA. This mechanism is designed for extensibility so that other ORB services can perform a poll as a part of the single poll operation described here.

• For the typed polling model (sendp), a client invokes the request’s type-specific Poller to receive the response. This poll can either block (wait for the completion) or return immediately if the request isn’t finished yet, depending on the value of the first parameter. Alternately, a client can simply query whether the request has completed by using the generic non-blocking CORBA::Pollable::is_ready( ) operation defined on the base interface that is inherited by all type-specific pollers.

For the sake of efficiency, it must be possible to query or block on multiple async pollers in a single operation. To do this, it is necessary to identify precisely, which such pollers are to be polled.

   The mechanism for generalized polling on multiple types of occurrences uses the CORBA::PollableSet interface.

   module CORBA {

   local interface PollableSet;

   abstract valuetype Pollable {boolean is_ready(in unsigned long timeout);

   PollableSet create_pollable_set( );};

   abstract valuetype DIIPollable : Pollable { };

   local interface PollableSet {

   exception NoPossiblePollable { };exception UnknownPollable { };

   DIIPollable create_dii_pollable();

   void add_pollable(in Pollable potential );

   Pollable get_ready_pollable(in unsigned long timeout) raises( NoPossiblePollable );

   void remove(in Pollable potential ) raises( UnknownPollable );

   unsigned short number_left( );

   };};

   7.4.1 Abstract Valuetype Pollable

   A Pollable supports queries to see if it is ready to be used, and can be registered with a pollable set to allow a single client thread to block on multiple potential happenings at the same time.

   7.4.1.1 is_ready

   boolean is_ready(in unsigned long timeout);

   Returns the value TRUE if and only if the specific happening represented by the pollable is ready to be consumed. Returns the value FALSE if the pollable is not yet ready to be consumed. If the timeout argument is the maximum value for unsigned long, the operation will block until it can return the value TRUE indicating that its happening is ready to be consumed. If the timeout argument is the value 0, the operation returns immediately.

   7.4.1.2 create_pollable_set

   PollableSet create_pollable_set( );

   Once there is a Pollable, it is possible to create a set of such pollables, which can be queried or upon which a client can block. The create_pollable_set operation creates a PollableSet object reference for an object with an empty set of pollable entities.

   7.4.2 Abstract Valuetype DIIPollable

   The specific Pollable that indicates interest in DII requests. A DIIPollable can be used in conjunction with a pollable set to allow a client to block or poll for the completion of DII requests, similar to the use of CORBA::ORB::get_next_response. When the DIIPollable is returned from PollableSet::poll, the reply to some DII request must be ready for processing.

   7.4.3 interface PollableSet

   The pollable set contains potential happenings for which a poll can be performed. The client adds potential happenings to the set and later queries the set to see if any have occurred. PollableSet is a locality constrained object.

   Note – There is a factory for PollableSet on the generic Pollable interface. Some implementation of this interface, such as a type-specific poller value, must first be accessible before a client can create a PollableSet.

   7.4.3.1 create_dii_pollable

   DIIPollable create_dii_pollable();

   Returns an instance of DIIPollable that can subsequently be registered to indicate interest in replies to DII requests.

   7.4.3.2 add_pollable

   void add_pollable(in Pollable potential );

   The add_pollable operation adds a potential happening to the PollableSet. The supplied Pollable parameter is some implementation that can be polled for readiness. To register interest in DII requests, an instance of DIIPollable is added to the pollable set.

   7.4.3.3 get_ready_pollable

   Pollable get_ready_pollable(in unsigned long timeout) raises( NoPossiblePollable );

   The get_ready_pollable operation asks the PollableSet if any of its potential happenings have occurred. The timeout parameter indicates how many milliseconds this call should wait until the response becomes available. If this timeout expires before a reply is available, the operation raises the standard system exception TIMEOUT. Any delegated invocations used by the implementation of this polling operation are subject to the single timeout parameter, which supersedes any ORB or thread-level timeout quality of service. Two specific values are of interest:

• 0 - the call is a non-blocking query that raises the standard system exception NO_RESPONSE if the reply is not immediately available.

• 232-1 - the maximum value for unsigned long indicates no timeout should be used. The query will not return until the reply is available.

   If the PollableSet contains no potential happenings, the NoPossiblePollable exception is raised. If an actual happening is returned, the PollableSet removes that happening from the set. For the typed Poller, removing the happening is necessary since its usefulness ends once the Poller completes. In the case of a DII happening, there may still be deferred requests outstanding; if this is the case, the client application must add the DIIPollable again to the PollableSet.

   When the get_ready_pollable operation blocks, the ORB has control of the thread and can process any work it has (such as receiving and dispatching requests through its Object Adapter). The get_ready_pollable operation can be used in an “event-style main loop? using ORB::work_pending and ORB::perform_work.

   If the ORB supports multiple threads, one thread may be blocking on a PollableSet while another is adding and removing potential happenings from the set. It is valid for the PollableSet to change dynamically while a poll is in progress. If another thread’s PollableSet::remove operation leaves the PollableSet empty, any blocked threads raise the NoPossiblePollable exception.

   7.4.3.4 remove

   void remove( in Pollable potential ) raises( UnknownPollable );

   The remove operation deletes the potential happening identified by the potential parameter from the PollableSet. If it was not a member of the set, the UnknownPollable exception is raised.

   7.4.3.5 number_left

   unsigned short number_left( );

   The number_left operation returns the number of potential happenings in the pollable set. A returned value of zero means that there are no potential happenings in the set, in which case a query on the set would raise the NoPossibleHappening exception.