Overview
Timeouts provide a means for an event request to be canceled if it is not satisfied within a predetermined period. Timeouts tend to not be required and they should be avoided where possible, as an arbitrary tolerance can introduce hard to detect and hard to repeat bugs. However, there are certain cases where a timeout is required.
Timeouts can be set to;
CLP_WAIT which specifies an infinite timeout, CLP_POLL which specifies a zero timeout, or a positive non-zero integer that specifies the number of milliseconds to wait for.
Consider the case of a thread receiving messages via a hardware device and writing data to one store and high-priority events to another:
If the store fills up then without a timeout then the thread will block, waiting to write to the store. This prevents the device from servicing any other events in the meantime and so high-priority events will not be delivered. In this case, it may be desirable to use a timeout and discard data that cannot be written within a certain period, in order to ensure that the high-priority events are still serviced.
Timeouts can also be used to test for the presence of an event. For example, a method can request a semaphore with a timeout of zero:
In this case, if the event request can be satisfied then the event is returned immediately, otherwise an error code is returned informing the method that the semaphore event was not available.
How to Specify Timeouts
Timeouts can be applied to store Open, propagator Wait or semaphore Request events. These timeouts (given in milliseconds) allow the call to return if the event cannot be satisfied within the specified time. The caller can then take any appropriate recovery action (e.g. try again, or report the error and throw away the event).
if ( EventSstCxn.OpenWrite( 0, CLP_NO_RULE, CLP_POLL ) )
{
// write to Event store
EventSstCxn.Close();
}
else
{
ClpDiag( "Event Store buffer full" );
// dont close the event - it wasn't opened
}
When using a timeout the caller must always check the return value, if the event failed then the connection has not been opened and any associated data has not been setup.
Although timeouts are specified in milliseconds, the actual time that the call blocks is platform/operating system dependent (e.g. Microsoft Windows XP has a 40ms resolution). However, a timeout of zero (CLP_POLL) will always return immediately. It is never a good idea to rely on perfect timing from any non-real time operating system, always think in terms of long-delay, short delay, immediate return or no return.