ChannelSets

This is a placeholder for future doc work on ChannelSets. See the Channels documentation for an example with more detail.

Description

TBD.

Example

TBD.

API

These are the user-facing API calls for ChannelSet objects.

Functions

DRAGON_GLOBAL_MAP(channelsets)

dragonError_t dragon_channelset_attr_init(dragonChannelSetAttrs_t *attrs)

Initialize a ChannelSet attributes structure.

When overriding default ChannelSet attributes, call this first to initialize the attributes structure before overriding individual attributes. This must be called before creating a ChannelSet with overridden attributes. The number of spin waiters, lock type, and synchronization type are all user specifiable. See the dragon_channelset_poll function for a description of synchronization.

Parameters:: attrs – A ChannelSet attributes structure
Returns:: DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channelset_create(dragonChannelDescr_t *descr_list[], int num_channels, const short event_mask, dragonMemoryPoolDescr_t *pool, dragonChannelSetAttrs_t *attrs, dragonChannelSetDescr_t *chset_descr)

Create a ChannelSet from a list of channels with possible attributes.

Creating a ChannelSet makes it possible to poll across a set of channels. The details of how this is accomplished is handled by the channel set API. A list of channels must be provided to poll across.

Parameters:

descr_list – An array of channel descriptors to be included in this ChannelSet.
num_channels – The size of the channel descriptor list.
event_mask – The event mask to use in monitoring for events on the channels.
pool – The memory pool to use for the ChannelSet.
attrs – The ChanneSet attributes. NULL may be specified to get the default attributes.
chset_descr – The ChannelSet descriptor which is initialized when DRAGON_SUCCESS is returned. The user provides the space for the ChannelSet descriptor.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channelset_destroy(dragonChannelSetDescr_t *chset_descr)

Destroy a ChannelSet.

A ChannelSet that is no longer needed should be destroyed. If it is not destroyed when no longer needed, it will leave its member channels in an unknown state.

Parameters:: chset_descr – An ChannelSet descriptor that was successfully created.
Returns:: DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channelset_get_channels(dragonChannelSetDescr_t *chset_descr, dragonChannelDescr_t **descr_list, int *num_channels)

Get the channel descriptors from a ChannelSet.

The descr_list will be a list of channel descriptors from this ChannelSet. Upon successful completion of the call, the num_channels will be set to the number of channels in the descr_list. The list must be freed via free, when it is no longer needed. ChannelSets are immutable, so once called, it will not change.

Parameters:

chset_descr – An ChannelSet descriptor that was successfully created.
descr_list – An array of Channel descriptors.
num_channels – A pointer to an integer which on successful completion will contain the number of channels in descr_list.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channelset_get_event_mask(dragonChannelSetDescr_t *chset_descr, short *event_mask)

Get the event mask from a ChannelSet.

When created an event mask is provided for a ChannelSet. This call is provided for completeness to get the current event mask.

Parameters:

chset_descr – A ChannelSet descriptor that was successfully created.
event_mask – A pointer to a short which will be initialized to the event mask upon successful completion of the call.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channelset_set_event_mask(dragonChannelSetDescr_t *chset_descr, short event_mask)

Set the event mask for a ChannelSet.

The event mask may be changed during the course of a ChannelSet’s lifetime. This call allows you to do that.

Parameters:

chset_descr – A ChannelSet descriptor that was successfully created.
event_mask – A short which will be used to change to the event mask upon successful completion of the call.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channelset_poll(dragonChannelSetDescr_t *chset_descr, dragonWaitMode_t wait_mode, timespec_t *timeout, dragonReleaseFun release_fun, void *release_arg, dragonChannelSetEventNotification_t **event)

Poll for a channel event on a ChannelSet.

This call polls a set of channels in an efficient, scalable manner for events satisfying the event mask specified when the ChannelSet was created or modified using the dragon_channelset_set_event_mask call.

The ChannelSet attribute sync_type, specified when the ChannelSet is created, may be set to DRAGON_SYNC in which case there must be a process polling on the ChannelSet for a channel to accept a message or send a message. In this way the ChannelSet will guarantee that no channel events are missed at the possible expense of slowing down the channels (depending on activity and the client implementation). The default sync_type is DRAGON_NO_SYNC. In this case it is possible for there to be missed poll events on channels. While a new message will always generate an event if there is a poller, there is a window where no polling is currently being executed then new messages may arrive and no poll event will be generated when the message arrives. In the case of specifying the default DRAGON_NO_SYNC behavior, the client application should initiate a poll in a thread or process and then scan all channels in the ChannelSet for any missed events.

Parameters:

chset_descr – A ChannelSet descriptor that was successfully created.
wait_mode – Either DRAGON_IDLE_WAIT, DRAGON_SPIN_WAIT, or DRAGON_ADAPTIVE_WAIT. Spin waiting requires more CPU time, but may be faster in some applications, while idle waiting conserves resources at the possible expense of more required time in the application. If the maximum spin waiters is reached, the channel set will automatically switch over to idle waiting.
timeout – If NULL, the application will wait indefinitely. Otherwise, it will return after a successful poll or time out.
release_fun – For some applications it may be desirable to release a resource once the application has sucessfully become a waiter on the poll. This functionality allows an application to close a small but possible window in synchronization in an application specific way.
release_arg – The arg to provide to release_fun when the resource is released. Only one arg is allowed, but that arg could be a composite struture if desired.
event – A pointer to a pointer. This must be a pointer, pointer to an event notification structure. The poll function will return the event by pointing the pointer, pointer to a new event structure. The user application must free the event space via a call to free once it is no longer needed.
release_fun – If non-NULL this function will be called when the process has become a waiter on this channelset. This is useful when there is a race condition between something else and waiting that must be closed. The function must take a void* argument, which is supplied here. The argument may be NULL. The function should return a dragonError_t return code of DRAGON_SUCCESS to indicate it was successful.
release_arg – This is the argument to the release_fun. It can be a pointer to any user-defined structure.
event – The event argument is a pointer to a pointer which will receive the result event. The space for the event return value must be freed by the caller. It contains both the event that occurred and the index into the list of channels in the channel set. If POLLNOTHING is returned as the event, then the channel that was indicated was destroyed while waiting on the channel set.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channelset_notify_callback(dragonChannelSetDescr_t *chset_descr, void *user_def_ptr, dragonWaitMode_t wait_mode, timespec_t *timeout, dragonReleaseFun release_fun, void *release_arg, dragonChannelSetNotifyCallback cb)

Poll for a channel event on a ChannelSet via a callback.

This call polls a set of channels in an efficient, scalable manner for events satisfying the event mask specified when the ChannelSet was created or modified using the dragon_channelset_set_event_mask call. A user-defined callback function is called in a thread once the event occurs.

See the poll function for a description of the synchronization behavior that also applies to this function call.

Parameters:

chset_descr – A ChannelSet descriptor that was successfully created.
user_def_ptr – A user-defined pointer to an argument that must be in thread shareable space with the thread of execution that makes this call.
wait_mode – Either DRAGON_IDLE_WAIT or DRAGON_SPIN_WAIT. Spin waiting requires more CPU time, but may be faster in some applications, while idle waiting conserves resources at the possible expense of more required time in the application. If the maximum spin waiters is reached, the channel set will automatically switch over to idle waiting.
timeout – If NULL, the application will wait indefinitely. Otherwise, it will return after a successful poll or time out.
release_fun – For some applications it may be desirable to release a resource once the application has sucessfully become a waiter on the poll. This functionality allows an application to close a small but possible window in synchronization in an application specific way.
release_arg – The arg to provide to release_fun when the resource is released. Only one arg is allowed, but that arg could be a composite struture if desired.
cb – A pointer to a function that must have the signature defined in dragonChannelSetNotifyCallback consisting of four arguments as defined in channelsets.h. The event pointer will point at the discovered event information. It must be freed via free once the event information is no longer needed. The err argument will indicate if the callback is successfully reporting an event or if an error occurred while waiting for an event. In the case of an error, the err_str will point to an error string with additional information. When an error occurs, the err_str must be freed once it is no longer needed.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channelset_notify_signal(dragonChannelSetDescr_t *chset_descr, dragonWaitMode_t wait_mode, timespec_t *timeout, dragonReleaseFun release_fun, void *release_arg, int sig, dragonChannelSetEventNotification_t **event_ptr_ptr, dragonError_t *drc, char **err_string)

Poll for a channel event on a ChannelSet via a signal interface.

This call polls a set of channels in an efficient, scalable manner for events satisfying the event mask specified when the ChannelSet was created or modified using the dragon_channelset_set_event_mask call. A user-defined signal is sent to the process via the signal interface when a poll event occurs.

See the poll function for a description of the synchronization behavior that also applies to this function call.

Parameters:

chset_descr – A ChannelSet descriptor that was successfully created.
wait_mode – Either DRAGON_IDLE_WAIT or DRAGON_SPIN_WAIT. Spin waiting requires more CPU time, but may be faster in some applications, while idle waiting conserves resources at the possible expense of more required time in the application. If the maximum spin waiters is reached, the channel set will automatically switch over to idle waiting.
timeout – If NULL, the application will wait indefinitely. Otherwise, it will return after a successful poll or time out.
release_fun – For some applications it may be desirable to release a resource once the application has sucessfully become a waiter on the poll. This functionality allows an application to close a small but possible window in synchronization in an application specific way.
release_arg – The arg to provide to release_fun when the resource is released. Only one arg is allowed, but that arg could be a composite struture if desired.
sig – The user-defined signal to send to the process.
event_ptr_ptr – The event pointer, pointer will point at the discovered event information when no error has occurred. It must be freed via free once the event information is no longer needed.
drc – The argument will indicate if the signal is successfully reporting an event or if an error occurred while waiting for an event.
err_string – In the case of an error, *err_str will point to an error string with additional information. When an error occurs, the *err_str must be freed once it is no longer needed.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channelset_reset(dragonChannelSetDescr_t *chset_descr)

Reset the channel set event monitor.

This function should be called only when there is a guarantee of no activity on all channels in the channel set. It resets the event monitor to the state that it was in immediately after creating it. It should only be needed to recover from an error condition.

Parameters:: chset_descr – A ChannelSet descriptor that was successfully created.
Returns:: DRAGON_SUCCESS or a return code to indicate what problem occurred.

Variables

static size_t throw_away_payload_sz