Channels

Constants

group channels_constants

The channels API constants.

Enums

enum dragonChannelOFlag_t

Open mode with existing channel.

Not yet implemented.

Values:

enumerator DRAGON_CHANNEL_EXCLUSIVE

enumerator DRAGON_CHANNEL_NONEXCLUSIVE

enum dragonChannelFC_t

Flow control options.

Not yet implemented

Values:

enumerator DRAGON_CHANNEL_FC_NONE

enumerator DRAGON_CHANNEL_FC_RESOURCES

enumerator DRAGON_CHANNEL_FC_MEMORY

enumerator DRAGON_CHANNEL_FC_MSGS

enum dragonChannelEvent_t

Channel Poll Event Mask.

This defines the valid poll operations. Combinations of the values below are only allowed when explicitly given in these constants. The POLLINOUT combination is allowed, but all other constants are valid only individually for channel poll operations.

Values:

enumerator DRAGON_CHANNEL_POLLNOTHING

Used for resetting an event mask. Setting an event mask to this value clears all flags.

enumerator DRAGON_CHANNEL_POLLIN

Wait for available message. If a timeout occurs, then poll will return with an appropriate return code. Otherwise, upon successful completion, a message arrived in the channel. NOTE: Due to the nature of channels, another process/thread may have already retrieved the message by the time the current process attempts to receive it.

enumerator DRAGON_CHANNEL_POLLOUT

Wait for available space in channel. If no timeout occurs, the poll operation returns when there is space in the channel. As with POLLIN, while space is available when poll returns from POLLOUT the space may be gone again before this process can send to the channel if multiple processes are sending to the channel simultaneously.

enumerator DRAGON_CHANNEL_POLLINOUT

Get notified of available messages or available space in channel. This effectively means that a process is notified of any changes to a channel.

enumerator DRAGON_CHANNEL_POLLEMPTY

Check that channel is empty. The poll operation returns when the channel becomes empty or when a timeout occurrs. If the channel is empty when poll is called it returns immediately.

enumerator DRAGON_CHANNEL_POLLFULL

Check whether channel is full. The poll operation returns when the channel becomes full or when a timeout occurs. If the channel is full when poll is called it returns immediately.

enumerator DRAGON_CHANNEL_POLLSIZE

Get the number of messages in the channel. In this case, unlike other calls to poll, the number of messages currently in the channel are return in place of the return code.

enumerator DRAGON_CHANNEL_POLLRESET

Resets the channel, immediately deleting all messages. The deleted messages are immediately cleared with no cleanup. The message contents are not freed, so resetting a channel does not change the reference counts of any messages or memory that might have been in the channel at the time of this call.

enumerator DRAGON_CHANNEL_POLLBARRIER_WAIT

When channel is used as a barrier, wait on barrier with this. Using the channel barrier support is further discussed in the channels description.

enumerator DRAGON_CHANNEL_POLLBARRIER_ABORT

When channel is a barrier, abort the barrier wait and notify current waiters.

enumerator DRAGON_CHANNEL_POLLBARRIER_RELEASE

When channel is a barrier, release all waiters from the barrier.

enumerator DRAGON_CHANNEL_POLLBARRIER_ISBROKEN

Check whether the barrier channel is broken or not. Broken is a state it can get into.

enumerator DRAGON_CHANNEL_POLLBARRIER_WAITERS

Return the number of waiters on the barrier channel.

enumerator DRAGON_CHANNEL_POLLBLOCKED_RECEIVERS

Return the number of blocked receivers on a channel.

enum dragonChannelFlags_t

Channel flags for Testing.

These flags are for test purposes only.

Values:

enumerator DRAGON_CHANNEL_FLAGS_NONE

Provides the default value.

enumerator DRAGON_CHANNEL_FLAGS_MASQUERADE_AS_REMOTE

This is a process local attribute only for testing

Variables

static dragonMemoryDescr_t *const DRAGON_CHANNEL_SEND_TRANSFER_OWNERSHIP = (dragonMemoryDescr_t*)1

Constant to be used for transfer of ownership of the message payload area on a send operation.

static timespec_t const DRAGON_CHANNEL_BLOCKING_NOTIMEOUT = {INT32_MAX, INT32_MAX}

Constant to be used for no timeout.

For send_msg and get_msg this would mean to wait with no timeout.

static timespec_t const DRAGON_CHANNEL_TRYONCE_TIMEOUT = {0, 0}

Try Once Timeout.

This indicates a try-once attempt. This works both on-node and off-node.

Structures

group channels_structs

The channels API structures.

Enums

enum dragonChannelRecvNotif_t

Receive Notification Type.

Not yet implemented.

Values:

enumerator DRAGON_RECV_SYNC_SIGNAL

enumerator DRAGON_RECV_SYNC_MANUAL

enum dragonGatewayMessageKind_t

Types of GatewayMessages.

This structure defines the types of GatewayMessages that can be ceated and must be supported by a transport agent.

Values:

enumerator DRAGON_GATEWAY_MESSAGE_SEND

A send operation

enumerator DRAGON_GATEWAY_MESSAGE_GET

A get operation

enumerator DRAGON_GATEWAY_MESSAGE_EVENT

An event monitoring operation

struct dragonChannelAttr_t

#include <channels.h>

The attributes structure of a Channel.

This structure contains members that can tune the channel size and performance characteristics. It is also used when retrieving the attributes from an existing channel. Setting and getting attributes from a channel only works on-node.

Public Members

dragonC_UID_t c_uid

The channel’s cuid. Read Only. Set it using a separate argument on dragon_channel_create.

size_t bytes_per_msg_block

The bytes per message block. Larger messages will be stored indirectly. Read/Write.

size_t capacity

The number of blocks in the channel. Read/Write

dragonLockKind_t lock_type

The type of locks to use inside the channel. Read/Write

dragonChannelOFlag_t oflag

Not implemented.

dragonChannelFC_t fc_type

Not implemented.

dragonULInt flags

must be a bitwise combination of dragonChannelFlags_t Read/Write

dragonMemoryPoolDescr_t *buffer_pool

The memory pool that is used for internal allocations. Read/Write

size_t max_spinners

The maximum allowed spin processes when waiting on the channel. More waiters are allowed, but will be IDLE waiters instead. Read/Write

size_t max_event_bcasts

The number of channelsets that can register this channel. Read/Write

int blocked_receivers

Number of receivers that are currently blocked. The value may change before the attributes are returned. Read Only.

int blocked_senders

Number of blocked receivers. The value may change before the attributes are returned. Read Only.

size_t num_msgs

Number of messages in the channel. The value may change before the attributes are returned. Read Only.

size_t num_avail_blocks

Number of available message blocks in the channel. It will always be capacity - num_msgs. It is a snapshot only. Read Only.

bool broken_barrier

A channel being used as a barrier is broken if this value is non-zero. Read-only.

int barrier_count

The number of waiters on this barrier. Waiting is a two-step operation, so this may differ from blocked_receivers. Read Only.

struct dragonChannelSendAttr_t

#include <channels.h>

Send Handle Attributes.

These attributes are provided on send handle creation.

Public Members

dragonUUID sendhid

Used internally by the Dragon run-time services.

dragonChannelSendReturnWhen_t return_mode

When to return from a send.

timespec_t default_timeout

Default timeout used when NULL is provided as the timeout override.

dragonWaitMode_t wait_mode

Either IDLE wait or SPIN wait may be specified.

struct dragonChannelRecvAttr_t

#include <channels.h>

Receive Handle Attributes.

The attributes are provided on receive handle creation.

Public Members

dragonChannelRecvNotif_t default_notif_type

Notification type is currently unused.

timespec_t default_timeout

Default timeout used when NULL is provided as the timeout override.

int signal

Signal is currently unused.

dragonWaitMode_t wait_mode

Either IDLE wait or SPIN wait may be specified.

struct dragonChannelDescr_t

#include <channels.h>

An opaque channel descriptor.

When a channel created, a channel descriptor is initialized for the current process. These channel descriptors may be shared with other processes by first serializing them, and then passing the serialized descriptor to another process. The other process must then attach to the channel using the serialized descriptor. Attaching and creating are the two means of initializing a channel descriptor.

struct dragonChannelSerial_t

#include <channels.h>

A serialized channel descriptor.

This is a two part structure providing an array of bytes and the length of that array.

Public Members

size_t len

The length of the serialized descriptor in bytes.

struct dragonChannelSendh_t

#include <channels.h>

An Opaque Channel Send Handle.

A send handle must be declared, intialized, and opened before sending to a channel.

struct dragonChannelRecvh_t

#include <channels.h>

An Opaque Channel Receive Handle.

An receive handle must be declared, initialized, and opened prior to receiving data.

struct dragonMessageAttr_t

#include <channels.h>

The attributes structure for tuning a Message.

This structure contains members that can tune Message behavior and can be used by a transport agent for operation handling for operations on remote Channels.

Public Members

dragonULInt hints

Placeholder of future hints about this message

dragonULInt clientid

An identifier of the process that sent this message

dragonUUID sendhid

An identifier of the send handle for the sending process used for ordering

bool send_transfer_ownership

Used to indicate cleanup by receiver. This can also be specified by providing dest_mem as DRAGON_CHANNEL_SEND_TRANSFER_OWNERSHIP.

struct dragonMessage_t

#include <channels.h>

An Opaque Message structure.

A message must be declared and intialized before it can be sent. Certain attributes can be provided when initializing the message by declaring and initializing a dragonMessageAttr_t structure.

struct dragonChannelEventNotification_t

#include <channels.h>

An Event Notification structure.

This is the event that occurred in a channelset notification.

Public Members

int user_token

An identifier associated with this event when it was registered.

short revent

The event that occurred.

struct dragonGatewayMessageHeader_t

#include <channels.h>

The Gateway Message Header.

This is provided here but used internally in the channels implementation and by a transport service when reading gateway messages from a gateway channel. All fields are internal use only unless definining a new transport service beyond those provided with Dragon. All fields are set via gateway message creation.

Public Members

dragonGatewayMessageKind_t *msg_kind

A send, get, or event message

dragonULInt *target_hostid

Hostid identifying the target of this request.

dragonULInt *has_deadline

If there is a timeout, then this points to true.

dragonULInt *deadline_sec

Seconds of the timeout

dragonULInt *deadline_nsec

Nanoseconds part of timeout

atomic_int_fast64_t *client_cmplt

Set to 1 when client has completed pickup.

dragonULInt *transport_cmplt_timestamp

Used for reporting after timeout.

dragonULInt *client_pid

Client PID useful in debugging.

dragonULInt *client_puid

non-zero when available.

dragonULInt *cmplt_bcast_offset

Offset of the completion bcast

dragonULInt *target_ch_ser_offset

The serialized descriptor of the target channel

dragonULInt *target_ch_ser_nbytes

Number of bytes in target channel serialized descriptor.

dragonULInt *send_payload_cleanup_required

Whether the transport is required to clean up.

dragonULInt *send_payload_buffered

If points to true, then send_payload_offset is offset to serialized descriptor

dragonULInt *send_payload_offset

When sending, the location of the message to send

dragonULInt *send_payload_nbytes

Number of bytes in send payload.

dragonULInt *send_clientid

used internally for message ordering.

dragonULInt *send_hints

provided on send operation and passed along.

dragonULInt *send_return_mode

provided on send operation and passed along.

dragonULInt *has_dest_mem_descr

On a get, a destination for the received message may be specified.

dragonULInt *dest_mem_descr_ser_offset

Where to put it if a destination was provided.

dragonULInt *dest_mem_descr_ser_nbytes

Size of descriptor when told where to place received message.

dragonULInt *op_rc

The gateway operation return code

dragonULInt *event_mask

On poll this is the poll event to monitor. On poll response it is the event that occurred.

dragonUUID *sendhid

Used in send ordering.

struct dragonGatewayMessage_t

#include <channels.h>

The Gateway Message structure for interacting with a transport agent.

This structure groups together all information about a message needed by a transport agent for completing the operation. Public members can be directly accessed for fast access to relevant data about the operation while private members facilitate coordination with a client process.

Public Members

dragonChannelSerial_t target_ch_ser

Serialize descriptor of the target Channel

dragonGatewayMessageKind_t msg_kind

The kind of message (send, get, event)

dragonULInt target_hostid

The hostid the target Channel is on

timespec_t deadline

When the operation must be completed by

dragonChannelSendReturnWhen_t send_return_mode

When a send operation should return to the caller

dragonMessage_t send_payload_message

The message being sent for send operations

dragonMemorySerial_t *send_dest_mem_descr_ser

Optional destination serialized memory descriptor for sends

dragonMemorySerial_t *get_dest_mem_descr_ser

Optional destination serialized memory descriptor for gets

short event_mask

Mask of events to monitor for event operations

struct dragonGatewayMessageSerial_t

#include <channels.h>

A serialized Gateway Message handle.

This structure cannot be used directly to manipulate a message. All manipulation of the Gateway Message occurs via its API functions. A process gets a serialized Gateway Message by calling serialize on a valid Gateway Message object.

The data is a serialized representation of a Gateway Message object that can be passed between processes and used to attach to the same object in another process or thread, such as a transport agent.

Public Members

size_t len

The length in bytes of the data member

uint8_t *data

A pointer to buffer containing the serialized representation

Message Lifecycle Management

group messages_lifecycle

Functions

dragonError_t dragon_channel_message_attr_init(dragonMessageAttr_t *attr)

Initialize a message attributes structure.

When creating user-defined send attributes, this function should be called first, to initialize it. Then the user may override desired attributes before using it in creating a send handle.

Parameters:

attr – A pointer to the send attributes structure.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_message_attr_destroy(dragonMessageAttr_t *attr)

Destroy channle message attributes.

Calling this guarantees cleanup of any resources that were allocated during the dragon_channel_message_attr_init function call. These two functions should be executed pairwise.

Parameters:

attr – A pointer to a send attributes structure that was previously initialized.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_message_init(dragonMessage_t *msg, dragonMemoryDescr_t *mem_descr, const dragonMessageAttr_t *mattr)

Initialize a new message for transfer through Channels.

Create a new Message that either wraps up an existing Managed Memory descriptor or is left empty so it can be later updated with a Managed Memory descriptor.

Parameters:

• msg – is a pointer to the dragonMessage structure to update.

• mem_descr – is a pointer to a Managed Memory descriptor to wrap up or NULL.

• mattr – is a pointer to Message attributes for the new Message or NULL to use default values.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_message_destroy(dragonMessage_t *msg, const _Bool free_mem_descr)

Destroy a Message.

Destroy the Message and optionally free an underlying Managed Memory allocation associated with it.

Parameters:

• msg – is a pointer to the dragonMessage structure to destroy.

• free_mem_descr – is a boolean indicating whether or not to free the underlying managed memory allocation.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

Message Functionality

group messages_functionality

Functions

dragonError_t dragon_channel_message_get_mem(const dragonMessage_t *msg, dragonMemoryDescr_t *mem_descr)

Get a Managed Memory descriptor associated with a Message.

Get a descriptor for the Managed Memory allocation associated with the Message. An error will be returned if the Message has no Managed Memory descriptor associated with it.

Parameters:

• msg – is a pointer to the dragonMessage structure.

• mem_descr – is a pointer to update with a Managed Memory descriptor.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_message_getattr(const dragonMessage_t *msg, dragonMessageAttr_t *attr)

Get Message attributes.

Get the attributes for an existing Message.

Parameters:

• msg – is a pointer to the dragonMessage structure.

• attr – is a pointer to update with an attributes structure.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_message_setattr(dragonMessage_t *msg, const dragonMessageAttr_t *attr)

Set Message attributes.

Set the attributes for an existing Message.

Parameters:

• msg – is a pointer to the dragonMessage structure to update with new attributes.

• attr – is a pointer to an attributes structure.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

Channel Lifecycle Management

group channels_lifecycle

Functions

dragonError_t dragon_channel_send_attr_init(dragonChannelSendAttr_t *send_attr)

Initialize a send attributes structure.

When custom send attributes are desired, this function should be called first, to initialize the to default values. Then the user may override desired attributes before using it in creating a send handle.

Parameters:

send_attr – is a pointer to the send attributes structure.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_recv_attr_init(dragonChannelRecvAttr_t *recv_attr)

Initialize a receive attributes structure.

When custom receive attributes are desired, this function should be called first to initialize them to default values. Then the user may override desired attributes before using it in creating a receive handle.

Parameters:

recv_attr – is a pointer to the receive attributes structure.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_attr_init(dragonChannelAttr_t *attr)

Initialize a channel attributes structure.

When custom channel attributes are desired, this function should be called first to initialize them to default values. Then the user may override desired attributes before using it in creating a channel.

Parameters:

attr – is a pointer to the channel attributes structure.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_send_attr_destroy(dragonChannelSendAttr_t *send_attr)

Destroy a channel send handle attributes structure.

Release any allocations or resources associated with a send handle attributes structure. This does not destroy the underlying channel.

Parameters:

send_attr – is a pointer to the channel send handle attributes structure.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_recv_attr_destroy(dragonChannelRecvAttr_t *recv_attr)

Destroy a channel recv handle attributes structure.

Release any allocations or resources associated with a recv handle attributes structure. This does not destroy the underlying channel.

Parameters:

recv_attr – is a pointer to the channel send handle attributes structure.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_attr_destroy(dragonChannelAttr_t *attr)

Destroy a channel attributes structure.

Release any allocations in the attributes structure. This does not destroy the underlying channel.

Parameters:

attr – is a pointer to the attributes structure that was previously inited.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_create(dragonChannelDescr_t *ch, const dragonC_UID_t c_uid, dragonMemoryPoolDescr_t *pool_descr, const dragonChannelAttr_t *attr)

Create a channel in a memory pool.

Create a channel in a memory pool with the given c_uid. While the c_uid is not enforced to be unique across the Dragon run-time services by this api, that is desirable and is left to the user of this API call. Unique c_uid values are enforced by this API call at the process level. If you need globally unique c_uids, then use the managed channel API instead which coordinates with the Dragon run-time services to insure global uniqueness. For transparent multi-node communication between channels, c_uids do not have to be unique across all nodes.

Parameters:

• ch – is the channel descriptor which will be initialzed from this call.

• c_uid – is a channel identifier. It must be unique on a process level and should be unique across all nodes. Read about uniqueness in the general description.

• pool_descr – is the pool in which to allocate this channel.

• attr – are the attributes to be used in creating this channel. If providing attributes, make sure you call dragon_channel_attr_init first. Otherwise, NULL can be provided to get default attributes.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_destroy(dragonChannelDescr_t *ch)

Destroy a channel.

Destroying a channel can only be done on the node where the channel is located. Destroying a channel frees the allocated memory in the memory pool and invalidates any use of the channel from this or other processes.

Parameters:

ch – is the channel descriptor to destroy.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_serialize(const dragonChannelDescr_t *ch, dragonChannelSerial_t *ch_ser)

Serialize a channel to be shared with another process.

Parameters:

• ch – is a channel descriptor for a channel.

• ch_ser – is a serialized channel descriptor that may be shared with another process.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_serial_free(dragonChannelSerial_t *ch_ser)

Free the internal resources of a serialized channel descriptor.

This frees internal structures of a serialized channel descriptor. It does not destroy the channel itself.

Parameters:

ch_ser – is a serialized channel descriptor.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_attach(const dragonChannelSerial_t *ch_ser, dragonChannelDescr_t *ch)

Attach to a channel.

Calling this attaches to a channel by using a serialized channel descriptor that was passed to this process. The serialized channel descriptor must have been created using the dragon_channel_serialize function.

Parameters:

• ch_ser – is a pointer to the serialized channel descriptor.

• ch – is a pointer to a channel descriptor that will be initialized by this call.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_detach(dragonChannelDescr_t *ch)

Detach from a channel.

Calling this will clean up any local references to a channel and release any local resources needed for communicating with the channel. It does not destroy the channel itself.

Parameters:

ch – is the channel descriptor from which to detach.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_descr_clone(dragonChannelDescr_t *newch_descr, const dragonChannelDescr_t *oldch_descr)

Clone a channel descriptor.

Calling this will copy a channel descriptor from one location to another. This does not copy the channel. It is used only for making a copy of a channel descriptor inside a process.

Parameters:

• newch_descr – is the channel descriptor space to copy into.

• oldch_descr – is the existing descriptor to clone.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

Channels Functionality

group channels_functionality

Functions

dragonError_t dragon_channel_get_pool(const dragonChannelDescr_t *ch, dragonMemoryPoolDescr_t *pool_descr)

Get pool from channel.

Given a channel, get the pool from the channel where it resides.

Parameters:

• ch – is a pointer to the channel descriptor.

• pool_descr – is a pointer the the pool descriptor that will be initialized by this call.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_get_hostid(const dragonChannelDescr_t *ch, dragonULInt *hostid)

Get the host identifier for a channel.

The host identifier is used to decide on which node the channel is hosted. This determines if it is a local channel or a remote channel. Sends and receives to/from remote channels are handled through gateway channels that must be registered prior to sending and or receiving. Gateway channels are shared with a process via an environment variable or variables. See register_gateways_from_env for more information on registering gateway channels. Host ids are arbitrary unsigned long integers and cannot not be interpreted or inferred from any other data.

Parameters:

• ch – is an initialized channel descriptor

• hostid – is a pointer to space to provide the hostid.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_get_uid_type(const dragonChannelSerial_t *ch_ser, dragonULInt *cuid, dragonULInt *type)

Get the channel’s cuid and/or type.

From a serialized channel descriptor, this function will return the cuid of the channel and the type of the channel. The channel is not attached while doing this.

Parameters:

• ch_ser – is a pointer to a serialied channel descriptor.

• cuid – is a pointer to a location there the cuid will be stored. If NULL is provided, the cuid is not copied from the channel descriptor.

• type – is a pointer to a location where the channel’s type will be stored. If NULL is provided, the type is not copied from the channel descriptor.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_pool_get_uid_fname(const dragonChannelSerial_t *ch_ser, dragonULInt *muid, char **pool_fname)

Get the muid and filename of a channel’s pool.

From a serialized channel descriptor, this function returns information about the pool the channel is allocated in, including the muid of the pool and the pool’s filename. The channel is not attached while doing this.

Parameters:

• ch_ser – is a pointer to a serialized channel descriptor.

• muid – is a pointer to a location where the muid of the pool will be stored. If NULL is provided, then the muid is not copied from the channel.

• pool_fname – is the filename associated with the shared memory of the channel’s pool.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

bool dragon_channel_is_local(const dragonChannelDescr_t *ch)

Check to see is a channel is local or not.

Returns true if a channel is local and false if not.

Parameters:

ch – is an intialized channel descriptor.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_sendh(const dragonChannelDescr_t *ch, dragonChannelSendh_t *ch_sh, const dragonChannelSendAttr_t *attr)

Initialize a send handle on a channel.

Calling this initializes a send handle on a channel. To use the send handle it must also be opened using the dragon_chsend_open function. Messages sent with a single send handle are guaranteed to be received from the channel in the same order. Order is maintained by both send and receive handles. If customized send handle attributes are to be supplied, dragon_channel_send_attr_init should be called first to initialize all attributes to default values before customizing the desired values.

Parameters:

• ch – is an initialized channel descriptor.

• ch_sh – is a pointer to a send handle descriptor that will be initialized by this call.

• attr – are send handle attributes that may be supplied when initializing the send handle. Providing NULL will result in the default send handle attributes being applied.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_chsend_get_attr(const dragonChannelSendh_t *ch_sh, dragonChannelSendAttr_t *attr)

Get the attributes of a send handle.

Copy the attributes from a send handle into a send attributes structure. The handle does not need to be open in order to get the attributes.

Parameters:

• ch_sh – A pointer to the channel send handle.

• attr – A pointer to the channel send handle attributes structure to copy into.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_chsend_open(dragonChannelSendh_t *ch_sh)

Open a channel send handle.

Open a send handle on a channel. Once opened, the send handle can be used for sending messages.

Parameters:

ch_sh – is a pointer to an initialized send handle.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_chsend_close(dragonChannelSendh_t *ch_sh)

Close a send handle.

Once sending is done on a particular send handle, it should be closed.

Parameters:

ch_sh – is a pointer to an open send handle.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_recvh(const dragonChannelDescr_t *ch, dragonChannelRecvh_t *ch_rh, const dragonChannelRecvAttr_t *rattrs)

Initialized a channel receive handle.

Initialize a receive handle structure given a channel. To use the receive handle it must also be opened using the dragon_chrecv_open function. Messages received with a single receive handle are guaranteed to be received from the channel in the same order they were sent. Order is maintained by both send and receive handles. If customized receive handle attributes are to be supplied, dragon_channel_recv_attr_init should be called first to initialize all attributes to default values before customizing the desired values.

Parameters:

• ch – is an initialized channel descriptor

• ch_rh – is a pointer to a structure that will be initalized by this call.

• rattrs – is a pointer to receive handle attributes. If NULL is provided, default receive handle attributes will be used.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_chrecv_get_attr(const dragonChannelRecvh_t *ch_rh, dragonChannelRecvAttr_t *attr)

Get the attributes for a receive handle.

Copy the attributes from a receive handle into a receive attributes structure. The handle does not need to be open in order to get the attributes.

Parameters:

• ch_rh – A pointer to the channel receive handle.

• attr – A pointer to the channel receive handle attributes structure to copy into.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_chrecv_open(dragonChannelRecvh_t *ch_rh)

Open a channel receive handle.

Once opened, a receive handle can be used to receive messages from a channel. Messages received from a receive handle are guaranteed to be received in the order they were sent.

Parameters:

ch_rh – is the receive handle to be opened.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_chrecv_close(dragonChannelRecvh_t *ch_rh)

Close a channel receive handle.

Once a receive handle is no longer to be used for receiving, the handle should be closed.

Parameters:

ch_rh – is a pointer to an open channel receive handle.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_chsend_send_msg(const dragonChannelSendh_t *ch_sh, const dragonMessage_t *msg_send, dragonMemoryDescr_t *dest_mem_descr, const timespec_t *timeout_override)

Send a message into a channel.

Much like putting data in a queue, messages can be sent through channels. Sending a message into a channel can be done in several ways. The destination memory descriptor (i.e. dest_mem_descr) may be NULL in which case the memory associated with the message to send will be copied upon sending. In that way the caller retains ownwership of the messages original memory allocation. If dest_mem_descr is non-NULL, then the message is copied into the dest_mem_descr before sending it. However, if dest_mem_descr is the special value DRAGON_CHANNEL_SEND_TRANSFER_OWNERSHIP, then this indicates the caller wishes to transfer the ownership of the memory allocation in msg_send to the receiver of this message. In this way, a zero-copy send operation is possible when sending on-node between processes. Using transfer of ownership also has performance advantages when communicating between nodes since the path through the transport agent then has fewer copies as well.

If a NULL dest_mem_descr is provided, the memory allocation for the message copy is made from either the channel’s pool (if the channel is local) or from the default memory pool for the node where the message is being sent from.

When a memory allocation is required because the dest_mem_descr is NULL, calling this function may block the sender until the memory allocation is available. This call will also block while waiting for exclusive access to the channel. If a timeout occurs on sending, then it was because the required memory was not available.

If a zero-byte destination memory descriptor is provided, this function will allocate memory from the pool indicated by the destination memory descriptor of the necessary size for the message being sent. When doing this, it might be that the pool and channel being sent to reside on a different node. This is acceptable and provides a means of directing a remotely sent message into a particular pool on a remote node. When this option is chosen, transfer of ownership of the original message can still be specified by setting the send transfer of ownership flag in the message attributes since you cannot specify a destination memory descriptor and transfer of ownership at the same time using the memory descriptor constant DRAGON_CHANNEL_SEND_TRANSFER_OWNERSHIP.

Parameters:

• ch_sh – is a pointer to an initialized and open send handle.

• msg_send – is a pointer to a valid channel message descriptor.

• dest_mem_descr – is a pointer to a destination memory descriptor. The detailed description above has more details on the valid values for this argument.

• timeout_override – is a pointer to a timeout structure that may be used to override the default send timeout as provided in the send handle attributes. A timeout of zero seconds and zero nanoseconds will result in a try-once call of send. A value of NULL will result in using the default timeout from the send handle attributes.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_chrecv_get_msg(const dragonChannelRecvh_t *ch_rh, dragonMessage_t *msg_recv)

Receive a message from a channel.

Calling this receives the next available message from a channel without blocking.

Parameters:

• ch_rh – is a pointer to an intialized and open receive handle structure.

• msg_recv – is a pointer to a message structure that will be initialized with the received message.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred. If no message is immediately available it will return DRAGON_CHANNEL_EMPTY.

dragonError_t dragon_chrecv_get_msg_notify(dragonChannelRecvh_t *ch_rh, dragonMessage_t *msg_recv, dragonBCastDescr_t *sync)

Asynchronously receive a message from a channel.

This function is not currently implemented.

Parameters:

• ch_rh – is a pointer to an initialized, open receive handle.

• msg_recv – is a pointer to a message descriptor to be initialzed aynchronously.

• sync – is a pointer to a BCast descriptor which points to a valid BCast object. The calling process can then wait on this BCast for a message to receive. This can be safely done by a thread of the calling process or by the process itself.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_chrecv_get_msg_blocking(const dragonChannelRecvh_t *ch_rh, dragonMessage_t *msg_recv, const timespec_t *timeout_override)

Receive a message from a channel.

This receives a message from a channel into the supplied message structure. A timeout override can be supplied to override the default timeout found in the channel receive handle. If the timeout_override is NULL, the default receive handle timeout is used. A timeout of zero seconds and zero nanoseconds will result in try once attempt which will return DRAGON_CHANNEL_EMPTY if no message is available.

Parameters:

• ch_rh – is a pointer to an initialized, open receive handle.

• msg_recv – is a pointer to a message descriptor which will be initialized by this call upon successful completion should a message be received.

• timeout_override – is a pointer to a structure that contains the timeout to use in place of the default handle timeout. If NULL, the default handle timeout is used. If zero seconds and nanoseconds, the call is non-blocking and returns the next message if availble or DRAGON_CHANNEL_EMPTY if no message is currently available.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_chrecv_peek_msg(const dragonChannelRecvh_t *ch_rh, dragonMessage_t *msg_peek)

Peek at a message from a channel.

This copies a message from a channel into the supplied message structure without removing the message from the channel.

Parameters:

• ch_rh – is a pointer to an initialized, open receive handle.

• msg_recv – is a pointer to a message descriptor which will be initialized by this call upon successful completion should a message be received.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_chrecv_pop_msg(const dragonChannelRecvh_t *ch_rh)

Pop a message from a channel.

This pairs with dragon_chrecv_peek_msg, removing a message from the channel. Calling this after dragon_chrecv_pop_msg will have the same effect as having called dragon_chrecv_get_msg with the same parameters. It is not required to call dragon_chrecv_pop_msg after calling dragon_chrecv_peek_msg().

Parameters:

ch_rh – is a pointer to an initialized, open receive handle.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_poll(const dragonChannelDescr_t *ch, dragonWaitMode_t wait_mode, const short event_mask, const timespec_t *timeout, dragonULInt *result)

Poll a channel for status or the occurrence of an event.

Polling may be done on any of the poll values found on dragonChannelEvent_t. The polling values POLLIN and POLLOUT may be done together with the value DRAGON_CHANNEL_POLLINOUT. All other polling event_masks must be done separately. They are not supported in combination with each other.

Parameters:

• ch – A channel descriptor for a channel either on-node or off-node.

• wait_mode – A choice between IDLE waiting or SPIN waiting for events polling. It is only relevant when polling for events.

• event_mask – This specifies one of the dragonChannelEvent_t constants.

• timeout – NULL indicates blocking with no timeout. Otherwise, blocks for the specified amount of time. If (0,0) is provided, then it is a non-blocking call.

• result – For all but the DRAGON_CHANNEL_POLLSIZE the result will be a 64-bit cast of the event_mask field. With DRAGON_CHANNEL_POLLSIZE it is the number of messages currently in the channel.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_message_count(const dragonChannelDescr_t *ch, uint64_t *count)

Get the number of messages in a channel.

This will return the number of messages found in a channel. The number of messages will be correct when queried, but may change before this function returns to the caller if other processes are interacting with the channel by sending or receiving messages.

Parameters:

• ch – is a pointer to an initialized channel descriptor.

• count – is a pointer to space for a 64 bit unsigned integer that will hold the number of messages found in the channel.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_barrier_waiters(const dragonChannelDescr_t *ch, uint64_t *count)

Return the number of waiters on a barrier.

This function returns the number of waiters on a barrier for either local or remote channels that are configured to support a barrier. This returns the number of processes that have called the barrier wait functionality via the proper poll argument.

Parameters:

• ch – a pointer to a channel descriptor

• count – a pointer to an integer that will hold the result.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_blocked_receivers(const dragonChannelDescr_t *ch, uint64_t *count)

Return the number of blocked receivers.

This function returns the number of blocked receivers on either a local or remote channel.

Parameters:

• ch – a pointer to a channel descriptor

• count – a pointer to an integer that will hold the result.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

bool dragon_channel_barrier_is_broken(const dragonChannelDescr_t *ch)

Return whether the barrier is broken or not.

Returns whether the barrier is broken or not.

Parameters:

ch – is a pointer to a valid channel descriptor.

Returns:

true or false

dragonError_t dragon_channel_get_attr(const dragonChannelDescr_t *ch, dragonChannelAttr_t *attr)

Get the attributes from a channel.

Calling this will initialize a channel attributes structure with read-only and user-specified attributes of the channel. Read-only attributes are supplied on this call so a caller may inspect the current state of the channel.

Parameters:

• ch – is a pointer to an initialized channel descriptor.

• attr – is a pointer to a channel attributes structure that will be initialized by this call.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_register_gateways_from_env()

Register gateway channels from the environment.

When communicating off-node by using a transport agent, the channels library will handle packaging send and receive requests and sending them to the transport agent via gateway channels. To enable this, the serialized descriptors of gateway channels are provided to processes via environment variables. Gateway registration is handled automatically from these environment variables by the channels library. However, in certain situations (think dragon bringup) it may be necessary to override the default behavior of the channels library and allow a process to register gateways at their own pre-determined moment. Any process started by the Dragon run-time services will have the appropriate gateway channels present in the environment. If the process’ environment changes after startup, then calling this function registers those gateway channels with the channels library.

Calling this function from single-node mode has no effect and does not hurt anything. Internally the library caches the result of registering gateways. Calling this function wipes out the cached value and re-registers the gateway channels from the environment.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_discard_gateways()

Discard the registered gateway channels.

Any register gateways may be discarded as part of a process’ tear down. This is generally not required, but for completeness is available.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_register_gateway(dragonChannelDescr_t *ch)

Register a channel as a gateway channel.

A local channel can be promoted to be a gateway channel so that messaging through non-local Channels can be passed through and serviced by a transport agent. This operation will take a local channel and register it as a Gateway. A particular channel can only be registered once for a given process or its threads.

This function is not thread-safe in that registering the same channel from multiple threads at the same time could allow a channel to be registered more than once.

Parameters:

ch – is a pointer to a channel descriptor for the channel to register.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_unregister_gateway(dragonChannelDescr_t *ch)

Unregister a Channel as a Gateway Channel.

Remove a previously registered Channel from the internally managed list of Gateway Channels. This removes it as a gateway for this process and any associated threads. It does nothing to deregister it for other processes and does nothing to the underlying channel.

Unregistering a gateway channel can only be safely done if all send and receive handles are closed for the current process and its threads, particularly if those send or receive handles refer to a a remote channel. If they are not closed, a send or receive handle could end up referring to a non-existent gateway channel.

Parameters:

ch – is a pointer to a Channel descriptor for the Channel to deregister.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_add_event_bcast(dragonChannelDescr_t *ch, dragonBCastSerial_t *ser_bcast, const short event_mask, int user_token, dragonULInt *channel_token)

Create a channel set from a list of channels with possible attributes.

You create a channel set when you wish to poll across a set of channels. The details of how this is accomplished is handled by the channel set API. In this call you provide a list of the channels you wish to poll across. To get the most efficient implementation of this multi-channel poll, if it is in your control, specify the same default bcast event descriptor in the channel attributes for each channel when it is created.

Parameters:

• ch – is a pointer to an initialized channel descriptor.

• ser_bcast – is a serialized BCast decriptor to be added to the channel.

• event_mask – is the event mask to be monitored in the channel and signaled via the given BCast object.

• user_token – is a user-supplied token to be provided when the BCast is triggered.

• channel_token – is a pointer to space for an unsigned integer that is returned as a channel identifier when the event is triggered for this channel. This is used by the channel itself, not by the caller, but is provided for subsequent event bcast calls on this channel.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_remove_event_bcast(dragonChannelDescr_t *ch, dragonULInt channel_token)

Remove an event BCast from this channel.

The channel_token returned when a process adds an event bcast to a channel can be used to subsequently delete the even bcast from the channel.

Parameters:

• ch – is a pointer to an initialized channel descriptor.

• channel_token – is the channel token that was provided when the event bcast was registered. It can be used to remove the event bcast from the channel.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_update_event_mask(dragonChannelDescr_t *ch, dragonULInt channel_token, const short event_mask)

Update the event mask of an event BCast.

If desired, this function can be called to update the event mask of a BCast object that is stored within a channel. This only updates the triggering event for the given channel.

Parameters:

• ch – is a pointer to an initialized channel descriptor.

• channel_token – is an unsigned integer identifier that was provided when the event bcast was registered.

• event_mask – is the new event mask to be applied to the event bcast.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

Gateway Message Lifecycle Management

group gateway_messages_lifecycle

Functions

dragonError_t dragon_channel_gatewaymessage_send_create(dragonMemoryPoolDescr_t *pool_descr, const dragonMessage_t *send_msg, dragonMemoryDescr_t *dest_mem_descr, const dragonChannelDescr_t *target_ch, const dragonChannelSendAttr_t *send_attr, const timespec_t *deadline, dragonGatewayMessage_t *gmsg)

Create a GatewayMessage for sending.

Create a new GatewayMessage for a send operation. The GatewayMessage will be allocated out of the given Managed Memory Pool. After creation, the message can be serialized and sent into a Gateway Channel for processing by a transport agent. The client synchronizes for completion with the transport agent by calling dragon_channel_gatewaymessage_client_send_cmplt().

This function is not intended for most Channels users. It is used internally to support Channels operations on remote nodes and other purpose-built libraries.

Parameters:

• pool_descr – is a pointer a Managed Memory Pool from which to allocate the message.

• send_msg – is a pointer to the message with a payload to send to a remote Channel.

• dest_mem_descr – is a pointer to a destination memory descriptor or NULL to let Channels decide where to place the payload on the remote side.

• target_ch – is a pointer to a descriptor for the remote target Channel.

• send_attr – is a pointer to the send handle attributes associated with the send operation.

• deadline – is a pointer to a struct indicating when the actual send operation must finish by as processed by a transport agent. A deadline in the past is equivalent to returning immediately once the operation has been attempted (ie try once without blocking). A NULL values indicates no deadline and dragon_channel_gatewaymessage_transport_send_cmplt() will only return when the operation completes.

• gmsg – is a pointer to the Gateway Message to update.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_gatewaymessage_get_create(dragonMemoryPoolDescr_t *pool_descr, dragonMemoryDescr_t *dest_mem_descr, const dragonChannelDescr_t *target_ch, const timespec_t *deadline, dragonGatewayMessage_t *gmsg)

Create a GatewayMessage for getting a message.

Create a new GatewayMessage for a get operation. The GatewayMessage will be allocated out of the given Managed Memory Pool. After creation, the message can be serialized and sent into a Gateway Channel for processing by a transport agent. The client synchronizes for completion with the transport agent by calling dragon_channel_gatewaymessage_client_get_cmplt().

This function is not intended for most Channels users. It is used internally to support Channels operations on remote nodes and other purpose-built libraries.

Parameters:

• pool_descr – is a pointer a Managed Memory Pool from which to allocate the message.

• dest_mem_descr – is a descriptor to Managed Memory to place the message into or NULL, which allows the library to decide where to place the message. The final destination of the message is given by the call to dragon_channel_gatewaymessage_client_get_cmplt().

• target_ch – is a pointer to a descriptor for the remote target Channel.

• deadline – is a pointer to a struct indicating when the actual send operation must finish by as processed by a transport agent. A deadline in the past is equivalent to returning immediately once the operation has been attempted (ie try once without blocking).

• gmsg – is a pointer to the Gateway Message to update.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_gatewaymessage_event_create(dragonMemoryPoolDescr_t *pool_descr, short events, const dragonChannelDescr_t *target_ch, const timespec_t *deadline, dragonGatewayMessage_t *gmsg)

Create a GatewayMessage for an event.

Create a new GatewayMessage for monitoring for events. The GatewayMessage will be allocated out of the given Managed Memory Pool. After creation, the message can be serialized and sent into a Gateway Channel for processing by a transport agent. The client synchronizes for completion with the transport agent by calling dragon_channel_gatewaymessage_client_event_cmplt().

This function is not intended for most Channels users. It is used internally to support Channels operations on remote nodes and other purpose-built libraries.

Parameters:

• pool_descr – is a pointer a Managed Memory Pool from which to allocate the message.

• events – is a mask of events to monitor for. If any of the requested events occur the operation will complete. The actual event that triggered will be returned in dragon_channel_gatewaymessage_client_event_cmplt().

• target_ch – is a pointer to a Channel descriptor for the remote target Channel.

• deadline – is a pointer to a struct indicating when the actual send operation must finish by as processed by a transport agent. A deadline in the past is equivalent to returning immediately once the operation has been attempted (ie try once without blocking).

• gmsg – is a pointer to the Gateway Message to update.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_gatewaymessage_destroy(dragonGatewayMessage_t *gmsg)

Destroy a GatewayMessage.

Destroy a GatewayMessage of any operation type. This call exists to allow a process to cleanup a GatewayMessage that is not otherwise needed and its use by the completion calls. Typically a direct call to this function is not needed.

This function is not intended for most Channels users. It is used internally to support Channels operations on remote nodes and other purpose-built libraries.

Parameters:

gmsg – is a pointer to the Gateway Message to destroy.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_gatewaymessage_serialize(const dragonGatewayMessage_t *gmsg, dragonGatewayMessageSerial_t *gmsg_ser)

Serialize a GatewayMessage.

Serialize a GatewayMessage so that another process can interact with the GatewayMessage once the serialized representation is attached to. The serialized representation can be communicated with another process (the transport agent) through any means (typically a Gateway Channel).

This function is not intended for most Channels users. It is used internally to support Channels operations on remote nodes and other purpose-built libraries.

Parameters:

• gmsg – is a pointer to the Gateway Message to serialize.

• gmsg_ser – is a pointer to the serialized Gateway Message message structure to update.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_gatewaymessage_serial_free(dragonGatewayMessageSerial_t *gmsg_ser)

Free a serialize GatewayMessage.

Clean up a serialized representation of a Gateway Message.

This function is not intended for most Channels users. It is used internally to support Channels operations on remote nodes and other purpose-built libraries.

Parameters:

gmsg_ser – is a pointer to the serialized Gateway Message message structure to clean up.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_gatewaymessage_attach(const dragonGatewayMessageSerial_t *gmsg_ser, dragonGatewayMessage_t *gmsg)

Attach to a serialized GatewayMessage.

Attach to an existing Gateway Message from a serialized representation. Once attached, a process can interact with the Gateway Message and access its members.

This function is not intended for most Channels users. It is used internally to support Channels operations on remote nodes and other purpose-built libraries.

Parameters:

• gmsg_ser – is a pointer to the serialized Gateway Message message structure that should be attached.

• gmsg – is a pointer to the Gateway Message to intialize with the attached message.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_gatewaymessage_detach(dragonGatewayMessage_t *gmsg)

Detach from a GatewayMessage.

Detaching from a Gateway Message is not typically done directly. The completion functions will internally do this and use this function.

This function is not intended for most Channels users. It is used internally to support Channels operations on remote nodes and other purpose-built libraries.

Parameters:

gmsg – is a pointer to the Gateway Message from which to detach.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

Gateway Message Functionality

group gateway_messages_functionality

Functions

dragonError_t dragon_channel_gatewaymessage_transport_start_send_cmplt(dragonGatewayMessage_t *gmsg, const dragonError_t op_err, timespec_t *deadline)

Start the completion of a send operation from a transport agent.

Once a transport agent has completed a send operation for the Gateway Message, this call is used to coordinate completion with the requesting client.

This function is not intended for most Channels users. It is used internally to support Channels operations on remote nodes and other purpose-built libraries.

Parameters:

• gmsg – is a pointer to the Gateway Message for send to complete.

• op_err – is an error code to propagate back to the client.

• deadline – is the timeout for coordinating with the client.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_gatewaymessage_transport_check_send_cmplt(dragonGatewayMessage_t *gmsg, timespec_t *deadline)

Check on the completion of a send operation from a transport agent.

Once a transport agent has completed a send operation for the Gateway Message, this call is used to coordinate completion with the requesting client. The given Gateway Message is not usable after return from this call.

This function is not intended for most Channels users. It is used internally to support Channels operations on remote nodes and other purpose-built libraries.

Parameters:

• gmsg – is a pointer to the Gateway Message for send to complete.

• deadline – is the timeout for coordinating with the client.

Returns:

DRAGON_SUCCESS, DRAGON_EAGAIN, DRAGON_TIMEOUT, or a return code to indicate what problem occurred.

dragonError_t dragon_channel_gatewaymessage_transport_send_cmplt(dragonGatewayMessage_t *gmsg, const dragonError_t op_err)

Complete a send operation from a transport agent.

Once a transport agent has completed a send operation for the Gateway Message, this call is used to coordinate completion with the requesting client. This function will manage cleanup of the Gateway Message. The given Gateway Message is not usable after return from this call.

This function is not intended for most Channels users. It is used internally to support Channels operations on remote nodes and other purpose-built libraries.

Parameters:

• gmsg – is a pointer to the Gateway Message for send to complete.

• op_err – is an error code to propagate back to the client.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_gatewaymessage_client_send_cmplt(dragonGatewayMessage_t *gmsg, const dragonWaitMode_t wait_mode)

Complete a send operation from a client.

Wait for completion of the given Gateway Message send operation. This function will manage cleanup of the Gateway Message. The given Gateway Message is not usable after return from this call.

This function is not intended for most Channels users. It is used internally to support Channels operations on remote nodes and other purpose-built libraries.

Parameters:

• gmsg – is a pointer to the Gateway Message for send to complete.

• wait_mode – is the type of waiting to do while the send completes: spin, idle, or adaptive.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_gatewaymessage_transport_start_get_cmplt(dragonGatewayMessage_t *gmsg, dragonMessage_t *msg_recv, const dragonError_t op_err, timespec_t *deadline)

Start the completion of a get operation from a transport agent.

Once a transport agent has completed a get operation for the Gateway Message, this call is used to coordinate completion with the requesting client.

This function is not intended for most Channels users. It is used internally to support Channels operations on remote nodes and other purpose-built libraries.

Parameters:

• gmsg – is a pointer to the Gateway Message for get to complete.

• msg_recv – is a pointer to the received Message that will be provided back to the client when the op_err argument is set to DRAGON_SUCCESS. Otherwise, it should be NULL.

• op_err – is an error code to propagate back to the client. DRAGON_SUCCESS indicates the requested message is returned. Otherwise, the error code reflects the error that occurred.

• deadine – is the timeout for coordination with the client

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred on the call.

dragonError_t dragon_channel_gatewaymessage_transport_check_get_cmplt(dragonGatewayMessage_t *gmsg, timespec_t *deadline)

Check on the completion of a get operation from a transport agent.

Once a transport agent has completed a get operation for the Gateway Message, this call is used to coordinate completion with the requesting client. The given Gateway Message is not usable after a successful return from this call.

This function is not intended for most Channels users. It is used internally to support Channels operations on remote nodes and other purpose-built libraries.

Parameters:

• gmsg – is a pointer to the Gateway Message for get to complete.

• deadine – is the timeout for coordination with the client

Returns:

DRAGON_SUCCESS, DRAGON_EAGAIN, DRAGON_TIMEOUT, or a return code to indicate what problem occurred on the call.

dragonError_t dragon_channel_gatewaymessage_transport_get_cmplt(dragonGatewayMessage_t *gmsg, dragonMessage_t *msg_recv, const dragonError_t op_err)

Complete a get operation from a transport agent.

Once a transport agent has completed a get operation for the Gateway Message, this call is used to coordinate completion with the requesting client. This function will manage cleanup of the Gateway Message. The given Gateway Message is not usable after return from this call.

This function is not intended for most Channels users. It is used internally to support Channels operations on remote nodes and other purpose-built libraries.

Parameters:

• gmsg – is a pointer to the Gateway Message for get to complete.

• msg_recv – is a pointer to the received Message that will be provided back to the client when the op_err argument is set to DRAGON_SUCCESS. Otherwise, it should be NULL.

• op_err – is an error code to propagate back to the client. DRAGON_SUCCESS indicates the requested message is returned. Otherwise, the error code reflects the error that occurred.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred on the call.

dragonError_t dragon_channel_gatewaymessage_client_get_cmplt(dragonGatewayMessage_t *gmsg, dragonMessage_t *msg_recv, const dragonWaitMode_t wait_mode)

Complete a get operation from a client.

Wait for completion of the given Gateway Message get operation. This function will manage cleanup of the Gateway Message. The given Gateway Message is not usable after return from this call.

This function is not intended for most Channels users. It is used internally to support Channels operations on remote nodes and other purpose-built libraries.

Parameters:

• gmsg – is a pointer to the Gateway Message for get to complete.

• msg_recv – is a pointer to a Message that will be updated with the received message when the return code is DRAGON_SUCCESS. Otherwise, the message is left uninitialized.

• wait_mode – is the type of waiting to do while the get completes: spin, idle, or adaptive.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_gatewaymessage_transport_start_event_cmplt(dragonGatewayMessage_t *gmsg, const dragonULInt result, const dragonError_t op_err, timespec_t *deadline)

Start the completion of an event operation from a transport agent.

Once a transport agent has completed an event operation for the Gateway Message, this call is used to coordinate completion with the requesting client.

This function is not intended for most Channels users. It is used internally to support Channels operations on remote nodes and other purpose-built libraries.

Parameters:

• gmsg – is a pointer to the Gateway Message for event to complete.

• result – is the result of calling the poll operation if there was a result to return. A valid result is only for those poll operations that return a result when the return value is DRAGON_SUCCESS.

• op_err – is an error code to propagate back to the client.

• deadline – is the timeout for the coordination with the client.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_gatewaymessage_transport_check_event_cmplt(dragonGatewayMessage_t *gmsg, timespec_t *deadline)

Check on the completion of an event operation from a transport agent.

Once a transport agent has completed an event operation for the Gateway Message, this call is used to coordinate completion with the requesting client. The given Gateway Message is not usable after return from this call.

This function is not intended for most Channels users. It is used internally to support Channels operations on remote nodes and other purpose-built libraries.

Parameters:

• gmsg – is a pointer to the Gateway Message for event to complete.

• deadline – is the timeout for the coordination with the client.

Returns:

DRAGON_SUCCESS, DRAGON_EAGAIN, DRAGON_TIMEOUT, or a return code to indicate what problem occurred.

dragonError_t dragon_channel_gatewaymessage_transport_event_cmplt(dragonGatewayMessage_t *gmsg, const dragonULInt result, const dragonError_t op_err)

Complete an event operation from a transport agent.

Once a transport agent has completed an event operation for the Gateway Message, this call is used to coordinate completion with the requesting client. This function will manage cleanup of the Gateway Message. The given Gateway Message is not usable after return from this call.

This function is not intended for most Channels users. It is used internally to support Channels operations on remote nodes and other purpose-built libraries.

Parameters:

• gmsg – is a pointer to the Gateway Message for event to complete.

• result – is the result of calling the poll operation if there was a result to return. A valid result is only for those poll operations that return a result when the return value is DRAGON_SUCCESS.

• op_err – is an error code to propagate back to the client.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_channel_gatewaymessage_client_event_cmplt(dragonGatewayMessage_t *gmsg, dragonULInt *event_result, const dragonWaitMode_t wait_mode)

Complete an event operation from a client.

Wait for completion of the given Gateway Message event operation. This function will manage cleanup of the Gateway Message. The given Gateway Message is not usable after return from this call.

This function is not intended for most Channels users. It is used internally to support Channels operations on remote nodes and other purpose-built libraries.

Parameters:

• gmsg – is a pointer to the Gateway Message for send to complete.

• event_result – is a pointer that will be updated with the triggered event.

• wait_mode – The type of wait to use while waiting: spin, idle, or adaptive.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.