File Like Interface

Constants

static dragonChannelDescr_t *const STREAM_CHANNEL_IS_MAIN_FOR_1_1_CONNECTION = (dragonChannelDescr_t*)0x0000000000001111: Constant to be used when opening a send and a receive handle as the stream channel argument when wishing to use the main channel as a stream channel. Both sender and receiver must have been designed to use this protocol since no run-time negotiation of this is provided.

static dragonChannelDescr_t *const STREAM_CHANNEL_IS_MAIN_FOR_BUFFERED_SEND = (dragonChannelDescr_t*)0x0000000000001112: Constant to be used when opening a send handle as the stream channel argument when wishing to send one message. Several sends may be done in the fli, but they will all be buffered (ignoring any buffer arguments on sends). The buffered data will be sent when the send handle is closed. The fli receiver code automatically handles any buffered data that was sent on the main channel and the client receiver code will have no idea that the data was sent this way. The client opens a receive handle as normal and receives the data.

Structures

struct dragonFLIAttr_t

#include <fli.h>

The attributes structure of an fli adapter.

This structure contains members that can tune the file-like interface (fli) adapter.

struct dragonFLISendAttr_t

#include <fli.h>

The send handle attributes of an fli send handle.

This structure contains members that can tune the send handle of a file-like interface (fli) adapter.

Public Members

dragonMemoryPoolDescr_t *dest_pool: dest_pool is a pool descriptor that can be used to indicate which pool will be used as the destination for sending data through a channel. This pool descriptor can be either a local or remote channel but must exist on the node where the data is sent. The default, NULL, will select the default pool on the destination node.

bool allow_strm_term: If true, then when the receiver closes the receive handle the sender will be notified via a DRAGON_EOT return code. The FLI will return this on any subsequent send operations once the receiver has canceled the stream. After stream cancelation, the sender should close the send handle since no more data will be sent. For short streams, one or two sent messages, this should be set to false. For longer streams of multiple message sends this should be set to true if there is some situation where the receiver may wish to terminate the stream prematurely. The sender controls this though, not the receiver. If the receiver closes a receive handle prematurely on a non-terminating stream, the rest of the stream will be sent by the sender and discarded automatically the FLI code when the receiver closes the receive handle. The default is false. Note: Stream termination is unavailable if the FLI is a buffered FLI.

bool turbo_mode: This may be set as an attribute on the FLI too. If set on the FLI, this argument is ignored. Otherwise, true indicates that data sent with transfer of ownership will be sent and sends will return immediately. This means that the sender may not know of a failure in sending and a receiver should likely have a timeout on receiving should something go wrong. The default is false.

bool flush: Flushing will insure a write into a send handle has been deposited even off-node when the send handle is closed. This will guarantee that the stream channel or buffered channel will contain the written data before the send handle close completes. Normally, this value can be false and perform faster if it is. On-node all data will be deposited, but when writing to off-node streams/channels, using flush will guarantee that it is deposited off-node as well before the send handle close completes. The default is false.

struct dragonFLIRecvAttr_t

#include <fli.h>

The receive handle attributes of an fli receive handle.

This structure contains members that can tune the receive handle of a file-like interface (fli) adapter.

Public Members

dragonMemoryPoolDescr_t *dest_pool: dest_pool is a pool descriptor that is used to copy the received message into when messages are received from the fli. While useful when using recv_mem, other receiving methods will use the pool as a transient space while receiving data and copy into process local storage before freeing the underlying pool data.

struct dragonFLIDescr_t

#include <fli.h>

An opaque fli descriptor.

When a file like interface adapter is created, an fli descriptor is initialized for the current process. These fli 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 fli adapter using the serialized descriptor. Attaching and creating are the two means of initializing an fli descriptor. Serializing and attaching are provided as convenience functions. FLI adapters can also be re-created from their component parts, but a serialized descriptor encapsulates the necessary component parts.

struct dragonFLISerial_t

#include <fli.h>

A serialized FLI adapter.

A serialized FLI adapter can be passed to other processes as a convenience for attaching from other processes. FLI adapters can also be re-created from their constituent parts.

Public Members

size_t len: The length of the serialized descriptor in bytes.

struct dragonFLISendHandleDescr_t

#include <fli.h>

An FLI Send Handle Descriptor.

When an adapter is open for sending, a send handle descriptor is provided which is initialized and used until closed. The send handle descriptor is an opaque reference to a send handle.

struct dragonFLIRecvHandleDescr_t

#include <fli.h>

An FLI Receive Handle Descriptor.

When an adapter is open for receiving, a recv handle descriptor is provided which is initialized and used until closed. The recv handle descriptor is an opaque reference to a recv handle.

FLI Lifecycle Management

dragonError_t dragon_fli_attr_init(dragonFLIAttr_t *attr)

Initialize attributes for a FLI adapter.

Initialize an attributes structure for FLI adapter customization. You initialize first by calling this function and then you can customize any of the attributes contained within the structure to suit your application.

Parameters:: attr – is a pointer to the attributes structure to be initialized.
Returns:: DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_fli_task_create(dragonFLIDescr_t *adapter, dragonChannelDescr_t *main_ch, dragonChannelDescr_t *mgr_ch, dragonChannelDescr_t *task_sem, dragonMemoryPoolDescr_t *pool, const dragonULInt num_strm_chs, dragonChannelDescr_t **strm_channels, const bool use_buffered_protocol, dragonFLIAttr_t *attrs)

Create an FLI adapter.

Please see dragon_fli_create for documentation on creating an FLI. Calling this task_create version adds an additional semaphore to the FLI that can be used to track tasks that are sent into the FLI and handle the tracking of when they are finished. In addition, this makes the created FLI joinable which means that processes can block until all tasks of the FLI, added to the semaphore count by calling task_create, have been completed by calling task_done.

Parameters:

adapter – is a descriptor and opaque handle to the FLI adapter and is initialized by this call.
main_ch – is a channel descriptor for the main channel of this FLI adapter. It is used internally in the adapter. After the life of the adapter it is up to user code to clean up this channel.
mgr_ch – is a channel used internally by the FLI adapter and not to be touched by user code during the life of the adapter. After the life of the adapter it is up to user code to clean up this channel. Supplying a NULL mgr_ch argument indicates this is either a buffered FLI adapter and must be accompanied by a value of 0 for the num_fli_chs argument or a stream channel will be supplied on all send operations.
sem_ch – is a channel used internally by the FLI adapter and not to be touched by user code during the life of the adapter. It is used, and must be created as, a semaphore. The channel attributes are used to specify that the channel is a semaphore channel when it is created. Call attr_init first for the channel, then set the semaphore attribute and create this channel before calling this FLI create function.
pool – is a pool to use for internal allocations necessary for the operation of the pool. If pool is NULL, then the pool of the main_ch channel will be used for required adapter allocations. If the main channel is not local, the default local pool will be used.
num_strm_chs – is the number of supplied stream channels that are provided on the creation of the FLI adapter. Each stream channel may be re-used and is used for one stream of messages that result from an open, multiple sends, and a close operation.
strm_channels – is an array of channel descriptors, num_strm_chs of them, that are being supplied on the adapter creation. See the longer discussion in the description of the adapter create above. The application is responsible for the clean up of these channels at the end of their life.
use_buffered_protocol – if true then only a main channel should be provided and no manager channel or stream channels are required. In this case all sent data is buffered into one message for all file write operations (all writes on an open send handle). The receiving side receives one message per conversation.
attr – is a pointer to the attributes structure that was previously inited. If the attr arg is NULL the default attributes will be used.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_fli_create(dragonFLIDescr_t *adapter, dragonChannelDescr_t *main_ch, dragonChannelDescr_t *mgr_ch, dragonMemoryPoolDescr_t *pool, const dragonULInt num_strm_chs, dragonChannelDescr_t **strm_channels, const bool use_buffered_protocol, dragonFLIAttr_t *attrs)

Create an FLI adapter.

An FLI adapter guarantees that a send and receive handle is between one sender and one receiver and will not have to deal with data interleaving from other processes. In addition, data may be streamed between the sender and receiver when the FLI adapter is not used in buffered mode. FLI adapters may be created in one of several modes.

When the main channel is provided the FLI adapter will be use in one of three modes.

In buffered mode the main channel is used to communicate on a many to many style connection where each send conversation is a complete conversation between a sender and a receiver. In this mode, if multiple sends are done, they are buffered before sending. In buffered mode receivers will receive the sent message as one receive operation, even if multiple sends were performed.
In non-buffered mode the main channel is a channel of stream channels and the API manages allocating a stream channel to an open send handle and providing that stream channel to a receiver by placing its serialized descriptor into the main channel to be picked up by opening a receive handle. In this case the main channel is used to manage 1:1 conversations between an open send handle and an open receive handle.

When using this mode, the stream channels come from one of two location. Either there is a manager channel which manages a set of stream channels to be used when sending data, OR a sender may provide a stream channel when opening the send handle.

There is one special case when a main channel is used in non-buffered mode and it is known that there is a single sender and single receiver using the FLI adapter. In this case, both the sender and receiver must specify a special constant of STREAM_CHANNEL_IS_MAIN_FOR_1_1_CONNECTION for the stream channel argument when opening the send handle and when opening the receive handle.

If the mgr_ch is not NULL, then it is used in one of a couple different ways. Please note: When creating an FLI adapter using the buffered protocol no manager channel should be specified.

When created in non-buffered mode, the manager channel contains a set of serialized descriptors for stream channels that will be provided to send handles when they are opened. If no main channel exists, then the stream channel must be provided when the receiver opens a receive handle. If stream channels are provided when the receive handle is opened then no main channel is required.
When the fli adapter is created, the user may provide a main channel, a manager channel, and a set of stream channels. In this case, the fli adapter will maintain the stream channels and dole them out and re-use them as send and receive handles are opened and closed, always guaranteeing that any conversation between sender and receiver is will not be interleaved with data from other processes.

If desired, a stream channel can be provided on either send handle open or receive handle open operations. In that way, the stream channel can be allocated by either the sender or receiver, but not both. When a stream channel is provided on a send or receive open operation your application must decide whether the senders or receivers will be supplying the stream channels. When stream channels are provided on send handle open operations, a manager channel is not necessary. When stream channels are provided on receive handle open operations, a main channel is not necessary.

Sharing FLI adapters is possible either by serializing and attaching to the adapter or by re-creating it from its constituent parts. NOTE: When re-creating an adapter by calling this function, the strm_channels should only be provided on the initial call to create. Providing them a second time will result in the channels being added more than once into the adapter which could lead to unpredictable results.

Parameters:

adapter – is a descriptor and opaque handle to the FLI adapter and is initialized by this call.
main_ch – is a channel descriptor for the main channel of this FLI adapter. It is used internally in the adapter. After the life of the adapter it is up to user code to clean up this channel.
mgr_ch – is a channel used internally by the FLI adapter and not to be touched by user code during the life of the adapter. After the life of the adapter it is up to user code to clean up this channel. Supplying a NULL mgr_ch argument indicates this is either a buffered FLI adapter and must be accompanied by a value of 0 for the num_fli_chs argument or a stream channel will be supplied on all send operations.
pool – is a pool to use for internal allocations necessary for the operation of the pool. If pool is NULL, then the pool of the main_ch channel will be used for required adapter allocations. If the main channel is not local, the default local pool will be used.
num_strm_chs – is the number of supplied stream channels that are provided on the creation of the FLI adapter. Each stream channel may be re-used and is used for one stream of messages that result from an open, multiple sends, and a close operation.
strm_channels – is an array of channel descriptors, num_strm_chs of them, that are being supplied on the adapter creation. See the longer discussion in the description of the adapter create above. The application is responsible for the clean up of these channels at the end of their life.
use_buffered_protocol – if true then only a main channel should be provided and no manager channel or stream channels are required. In this case all sent data is buffered into one message for all file write operations (all writes on an open send handle). The receiving side receives one message per conversation.
attr – is a pointer to the attributes structure that was previously inited. If the attr arg is NULL the default attributes will be used.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_fli_destroy(dragonFLIDescr_t *adapter)

Destroy the adapter.

All internal, process local resources are freed by making this call. Calling destroy does not destroy the underlying channels which were provided when the adapter was created.

Parameters:: adapter – is a descriptor and opaque handle to the FLI adapter.
Returns:: DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_fli_serialize(const dragonFLIDescr_t *adapter, dragonFLISerial_t *serial)

Serialize a FLI adapter.

This enable sharing with another process. When sharing an FLI adapter with another process you may use this function to create a shareable serialized descriptor. This creates a binary string which may not be ASCII compliant. Before sharing, if ASCII compliance is required, call a base64 encoder like the dragon_base64_encode found in dragon/utils.h before sharing and dragon_base64_decode before attaching from the other process.

NOTE: You must call dragon_fli_serial_free to free a serialized descriptor after calling this function to free the extra space allocated by this function once you are done with the serialized descriptor.

Parameters:

adapter – is a valid FLI adapter that has previously been created or attached.
serial – is a serialized descriptor that will be initialized with the correct byte count and serialized bytes for so it can be passed to another process.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_fli_serial_free(dragonFLISerial_t *serial)

Free the internal resources of a serialized FLI descriptor.

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

Parameters:: serial – is a serialized FLI descriptor.
Returns:: DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_fli_attach(const dragonFLISerial_t *serial, const dragonMemoryPoolDescr_t *pool, dragonFLIDescr_t *adapter)

Attach to an FLI adapter.

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

Parameters:

serial – is a pointer to the serialized FLI descriptor.
pool – is the pool to use for memory allocations when sending or receiving on this adapter. If NULL is provided, then the default node-local memory pool will be used.
adapter – is a pointer to an FLI descriptor that will be initialized by this call.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_fli_detach(dragonFLIDescr_t *adapter)

Detach from an adapter.

All internal, process local resources are freed by making this call. Calling detach does not destroy or detach the underlying channels which were provided when the adapter was created.

Parameters:: adapter – is a descriptor and opaque handle to the FLI adapter.
Returns:: DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_fli_get_available_streams(dragonFLIDescr_t *adapter, uint64_t *num_streams, const timespec_t *timeout)

Get available stream channels from adapter.

Get the number of stream channels currently available in the manager FLI. This provides a count of the number of channels currently held in reserve in the FLI

Parameters:

adapter – is a descriptor and opaque handle to the FLI adapter.
count – is a pointer to an integer result when DRAGON_SUCCESS is returned. Otherwise the value will be 0.
timeout – is the amount of time to wait. A NULL timeout means to wait indefinitely.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_fli_is_buffered(const dragonFLIDescr_t *adapter, bool *is_buffered)

Query if this FLI is a buffered FLI.

Sets the is_buffered flag accordingly if the FLI is buffered or not.

Parameters:

adapter – is a descriptor and opaque handle to the FLI adapter.
is_buffered – is a pointer to a bool result.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_fli_new_task(const dragonFLIDescr_t *adapter, const timespec_t *timeout)

Indicate a new task if being tracked on the FLI.

Increments the number of tasks on a task FLI. This should only be called after a successful send operation on the FLI, either bytes or memory. The number of tasks in incremented by 1.

Parameters:: adapter – is a descriptor and opaque handle to the FLI adapter.
Returns:: DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_fli_task_done(const dragonFLIDescr_t *adapter, const timespec_t *timeout)

Indicate a task is done on a task FLI.

Decrements the number of tasks completed on a task FLI. This must only be called after a successful new_task operation on the FLI. It indicates the task has now completed.

Parameters:: adapter – is a descriptor and opaque handle to the FLI adapter.
Returns:: DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_fli_join(const dragonFLIDescr_t *adapter, const timespec_t *timeout)

Block until the number of tasks has reached zero.

Blocks when the number of tasks is not zero.

Parameters:: adapter – is a descriptor and opaque handle to the FLI adapter.
Returns:: DRAGON_SUCCESS or a return code to indicate what problem occurred.

FLI Send/Recv Handle Management

dragonError_t dragon_fli_send_attr_init(dragonFLISendAttr_t *attrs)

Initialize a send handle attributes structure.

Call this before setting individual attributes within the structure to customize the send handle. See the dragonFLISendAttr_t definition for possible customizable values.

dragonError_t dragon_fli_open_send_handle(const dragonFLIDescr_t *adapter, dragonFLISendHandleDescr_t *send_handle, dragonChannelDescr_t *strm_ch, dragonFLISendAttr_t *attrs, const timespec_t *timeout)

Open a Send Handle.

When writing to the file like adapter interface you must first open a send handle, write using the send operation, and then close the send handle. The adapter guarantees that a receiver will receive the data in the same order it was sent, but not necessarily in the same size chunks.

As a special case, when there is a known single receiver and single sender using this FLI adapter, the special constant STREAM_CHANNEL_IS_MAIN_FOR_1_1_CONNECTION may be used for this stream channel argument. In that case, the same constant must be used for the stream channel when opening the receive handle. No manager channel should exist in this case. As the constant indicates, the main channel will be used as the stream channel in this special case.

A second special case is also possible. When an FLI has been created to allow streams (i.e. it has a main channel, a manager channel, or both that normally are used to manage stream channels), you can specify that the stream channel be STREAM_CHANNEL_IS_MAIN_FOR_BUFFERED_SEND. In this case, the normal streaming behavior is overridden for this send handle and instead data that is written to the send handle is buffered and sent in one send once the send handle is closed. This can be advantageous in eliminating the overhead of getting a stream channel and sending through it for smaller, single messages. In this case the receiver does not need to do anything special to receive the message. The FLI manages this internally without the receiver doing anything special.

Parameters:

adapter – is a created or attached FLI descriptor.
send_handle – is a send handle that will be initialized by this call and is to be used on subsequent send operations until this stream is closed.
strm_ch – is a stream channel to be used as a direct connection to a receiving process. A stream channel can only be specified for a receiver or a sender, but not both.
attrs – Several attributes of the send handle are customizable through the send handle attributes. See the dragonFLISendAttr_t structure for the possible customizations.
timeout – is a pointer to a timeout structure. If NULL, then wait forever with no timeout. If not NULL, then wait for the specified amount of time and return DRAGON_TIMEOUT if not sucessful. If 0,0 is provided, then that indicates that a try-once attempt is to be made.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_fli_close_send_handle(dragonFLISendHandleDescr_t *send_handle, const timespec_t *timeout)

Close a Send Handle.

All send operations between an open and a close operation are guaranteed to be received in order by a receiving process. A send handle should be closed once the sender has completed sending data. Any buffered data is sent upon closing the send handle.

Parameters:

send_handle – is the open send handle to be closed.
timeout – to be used in attempting to send to the adapter’s channel.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_fli_recv_attr_init(dragonFLIRecvAttr_t *attrs)

Initialize a receive handle attributes structure.

Call this before setting individual attributes within the structure to customize the receive handle. See the dragonFLIRecvAttr_t definition for possible customizable values.

dragonError_t dragon_fli_open_recv_handle(const dragonFLIDescr_t *adapter, dragonFLIRecvHandleDescr_t *recv_handle, dragonChannelDescr_t *strm_ch, dragonFLIRecvAttr_t *attrs, const timespec_t *timeout)

Open a Receive Handle.

When receiving from the file like adapter interface you must first open a receive handle, receive using the recv operation, and then close the receive handle. The adapter guarantees that a receiver will receive the data in the same order it was sent, but not necessarily in the same size chunks.

As a special case, when there is a known single receiver and single sending using this FLI adapter, the special constant STREAM_CHANNEL_IS_MAIN_FOR_1_1_CONNECTION may be used for this stream channel argument. In that case, the same constant must be used for the stream channel when opening the send handle. No manager channel should exist in this case. As the constant indicates, the main channel will be used as the stream channel in this special case.

Parameters:

adapter – is a created or attached FLI descriptor.
recv_handle – is a receive handle that will be initialized by this call and is to be used on subsequent recv operations until this stream is closed.
strm_ch – is a stream channel to be used as a direct connection to a receiving process. A stream channel can only be specified for a receiver or a sender, but not both. When using the buffered protocol it is not valid to use a stream channel. When not providing a stream channel, NULL should be specified.
attrs – Several attributes of the receive handle are customizable through the receive handle attributes. See the dragonFLIRecvAttr_t structure for the possible customizations.
timeout – is a pointer to a timeout structure. If NULL, then wait forever with no timeout. If not NULL, then wait for the specified amount of time and return DRAGON_TIMEOUT if not sucessful. If 0,0 is provided, then that indicates that a try-once attempt is to be made.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_fli_close_recv_handle(dragonFLIRecvHandleDescr_t *recv_handle, const timespec_t *timeout)

Close a Recv Handle.

All receive operations between an open and a close operation are guaranteed to be received in order by a receiving process. A recv handle should be closed once the sender has completed sending data. End of transmission will be indicated by a return code on a recv operation.

Parameters:

recv_handle – is the open receive handle to be closed.
timeout – is used for returning the stream channel to the adapter in some configurations. Otherwise it is ignored.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_fli_set_free_flag(dragonFLIRecvHandleDescr_t *recv_handle)

Set the free memory flag.

Set a flag in receive handle to indicate that the dragon managed memory that is received on this receive handle should be freed. This is the default behavior.

Parameters:: recv_handle – is an open receive handle.
Returns:: DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_fli_reset_free_flag(dragonFLIRecvHandleDescr_t *recv_handle)

Reset the free memory flag.

Reset a flag in receive handle to indicate that the dragon managed memory that is received on this receive handle should be freed. Resetting it means that the memory will not be freed as it is received.

Parameters:: recv_handle – is an open receive handle.
Returns:: DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_fli_stream_received(dragonFLIRecvHandleDescr_t *recv_handle, bool *stream_received)

Check that a Stream is completely received.

Check a receive handle to see if a stream has been completely received.

Parameters:

recv_handle – is the open receive handle to be queried.
stream_received – is set upon successful completion.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_fli_create_writable_fd(dragonFLISendHandleDescr_t *send_handle, int *fd_ptr, const bool buffer, size_t chunk_size, const uint64_t arg, const timespec_t *timeout)

Create a file descriptor to send bytes over an FLI adapter.

All writes to the file descriptor will be sent over the FLI adapter. Writes are either buffered or sent immediately as chosen on the call to this function. Internally, an send handle is opened when the file descriptor is created and closed when the file descriptor is closed. A stream channel may be supplied depending on the chosen form of transport. The timeout

Parameters:

adapter – is a created or attached FLI descriptor.
send_handle – is a send_handle for the FLI descriptor. It should be initialized before calling this function. After closing the returned file descriptor, the send_handle should also be closed to insure proper operation.
fd_ptr – is a pointer to an integer. The integer will be initialized to the file descriptor value.
buffer – is a constant of either false (or 0 or NULL), which means use the default behavior, or true in which case it buffers the data until the file descriptor is closed.
chunk_size – is the size of chunks that are attempted to be read from the file descriptor on each send operation. This can be used to fine-tune message sending efficiency through the file descriptor. A chunk size of 0 will result in using the default chunk size of 1K chunks.
arg – is a user-defined 64-bit argument to be passed through on the writes to the fli. This argument is not retrievable via a readable file descriptor, but it is accessible via other method of reading from the fli.
timeout – is a pointer to a timeout structure. If NULL, then wait forever with no timeout to open the file descriptor. If not NULL, then wait for the specified amount of time and return DRAGON_TIMEOUT if not sucessful. If 0,0 is provided, then that indicates that a try-once attempt is to be made.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_fli_finalize_writable_fd(dragonFLISendHandleDescr_t *send_handle)

Finalize and destroy the writable file descriptor.

This should be called after closing the created writable file descriptor to insure that all buffers are flushed before continuing to use the send handle. Note that calling this will hang if the file descriptor has not been closed prior to this call.

Parameters:: send_handle – is a valid send handle that was previously used to create a writable file descriptor.
Returns:: DRAGON_SUCESS or a return code to indicate what problem occurred.

dragonError_t dragon_fli_create_readable_fd(dragonFLIRecvHandleDescr_t *recv_handle, int *fd_ptr, const timespec_t *timeout)

Create a file descriptor to receive bytes over an FLI adapter.

All reads from the file descriptor will be received over the FLI adapter. Receives are returned as they were sent. If buffering was used during sending, then reads from the file descriptor may not match in size and quantity that writes were done. However, total quantity of bytes of information will be as it was sent. Internally, a receive handle is opened when the file descriptor is created and closed when the file descriptor signals end of stream. A stream channel may be supplied depending on the chosen form of transport.

Parameters:

adapter – is a created or attached FLI descriptor.
recv_handle – is a recv_handle for the FLI descriptor. It should be initialized before calling this function. After closing the returned file descriptor, the recv_handle should also be closed to insure proper operation.
fd_ptr – is a pointer to an integer. The integer will be initialized to the file descriptor value.
timeout – is a pointer to a timeout structure. If NULL, then wait forever with no timeout to open the file descriptor. If not NULL, then wait for the specified amount of time and return DRAGON_TIMEOUT if not sucessful. If 0,0 is provided, then that indicates that a try-once attempt is to be made.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_fli_finalize_readable_fd(dragonFLIRecvHandleDescr_t *recv_handle)

Finalize and destroy the readable file descriptor.

This should be called after closing the created readable file descriptor to insure that all buffers are flushed before continuing to use the receive handle. Note that calling this will hang if the file descriptor has not been closed prior to this call.

Parameters:: recv_handle – is a valid receive handle that was previously used to create a readable file descriptor.
Returns:: DRAGON_SUCESS or a return code to indicate what problem occurred.

FLI Send/Recv Functions

dragonError_t dragon_fli_send_bytes(dragonFLISendHandleDescr_t *send_handle, size_t num_bytes, uint8_t *bytes, uint64_t arg, const bool buffer, const timespec_t *timeout)

Send bytes through the FLI adapter.

All send operations between an open and a close of a send handle are guaranteed to be received by one receiver in the order they were sent.

Parameters:

send_handle – is an open send handle.
num_bytes – is the number of bytes to be sent and must be greater than zero.
bytes – is a pointer to the data to be sent.
arg – is meta-data assigned in a 64-bit field that can be set and will be received by the receiving side. It does not affect the message itself. When using the buffered protocol, only the first write into an open send handle will allow this arg to be passed along. All other values of this arg on subsequent writes to an open send handle are ignored. The value of 0xFFFFFFFFFFFFFFFF is used internally and is not allowed.
buffer – is a constant of either false (or 0 or NULL), which means use the default behavior, or true in which case it buffers the data until it is told to flush the data by either sending more data with buffer == false or by closing the send handle. This is only valid when NOT using the buffered protocol and you want to buffer the data into one message before sending. This argument is ignored when sending via a buffered adapter.
timeout – is a pointer to a timeout structure. If NULL, then wait forever with no timeout. If not NULL, then wait for the specified amount of time and return DRAGON_TIMEOUT if not sucessful. If 0,0 is provided, then that indicates that a try-once attempt is to be made.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_fli_get_buffered_bytes(dragonFLISendHandleDescr_t *send_handle, dragonMemoryDescr_t *mem_descr, uint64_t *arg, const timespec_t *timeout)

Get the bytes buffered for sending.

If data was buffered before sending, then calling this will return the bytes that were buffered for sending in a memory descriptor AND remove them from the buffered bytes of the FLI send handle. To send them, the user should subsequently call dragon_fli_send_mem.

Parameters:

send_handle – is an open send handle.
mem_descr – is a pointer to space for a memory descriptor that will be initialized by this call. If there are no bytes buffered to send, then calling this function will return a zero-byte allocation in the memory descriptor.
arg – is a pointer to space to hold the buffered arg value. NULL can be provided if the user does not need the arg value associated with the buffered data.
timeout – is a pointer to a timeout structure. If NULL, then wait forever with no timeout. If not NULL, then wait for the specified amount of time and return DRAGON_TIMEOUT if not sucessful. If 0,0 is provided, then that indicates that a try-once attempt is to be made.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_fli_send_mem(dragonFLISendHandleDescr_t *send_handle, dragonMemoryDescr_t *mem, uint64_t arg, bool transfer_ownership, bool no_copy_read_only, const timespec_t *timeout)

Send shared memory through the FLI adapter.

All send operations between an open and a close of a send handle are guaranteed to be received by one receiver in the order they were sent.

Parameters:

mem – is a memory descriptor pointer to Dragon managed memory to be sent.
arg – is meta-data assigned in a 64-bit field that can be set and will be received by the receiving side. It does not affect the message itself. When using the buffered protocol, only the first write into an open send handle will allow this arg to be passed along. All other values of this arg on subsequent writes to an open send handle are ignored. The value of 0xFFFFFFFFFFFFFFFF is used internally and is not allowed.
transfer_ownership – is true if ownership of the managed memory should be transferred to the receiver. Passing false means the ownership remains with the sender. This also implies a copy is made on sending.
no_copy_read_only – is true when the original memory allocation should be sent, but will not be cleaned up by anything receiving it due to the read-only nature of the memory being sent. The receiver must be aware of this read-only nature. It will not be notified of this attribute by the sender.
no_copy_read_only – is true when the original memory allocation should be sent, but will not be cleaned up by anything receiving it due to the read-only nature of the memory being sent. The receiver must be aware of this read-only nature. It will not be notified of this attribute by the sender.
timeout – is a pointer to a timeout structure. If NULL, then wait forever with no timeout. If not NULL, then wait for the specified amount of time and return DRAGON_TIMEOUT if not sucessful. If 0,0 is provided, then that indicates that a try-once attempt is to be made.

Returns:

DRAGON_SUCCESS or a return code to indicate what problem occurred.

dragonError_t dragon_fli_recv_bytes(dragonFLIRecvHandleDescr_t *recv_handle, size_t requested_size, size_t *received_size, uint8_t **bytes, uint64_t *arg, const timespec_t *timeout)

Receive data from the FLI adapter.

All receive operations between an open and a close of a recv handle are guaranteed to be received by one receiver in the order they were sent. If the return code comes comes back with DRAGON_EOT, then there is no more data to be received. When DRAGON_EOT is returned there may be valid data with it. The num_bytes will always indicate the amount of valid data returned.

Parameters:

recv_handle – is an open send handle.
requested_size – is the maximum number of bytes to receive. There may be less bytes received. num_bytes provides the actual number of bytes read. If requested_size==0 then all available bytes are read.
received_size – is a pointer to a variable that will be initialized with the number of received bytes.
bytes – points to a pointer that will be initialized with the received bytes. The space pointed to by bytes after this call must be freed.
arg – is a pointer to meta-data assigned in a 64-bit unsigned integer by the sender when the data was sent. If NULL is provided, the arg is not returned.
timeout – is a pointer to a timeout structure. If NULL, then wait forever with no timeout. If not NULL, then wait for the specified amount of time and return DRAGON_TIMEOUT if not sucessful. If 0,0 is provided, then that indicates that a try-once attempt is to be made.

Returns:

DRAGON_SUCCESS, DRAGON_EOT or a return code to indicate what problem occurred. When DRAGON_EOT is returned there may also be bytes that were read or there may be zero bytes read.

dragonError_t dragon_fli_recv_bytes_into(dragonFLIRecvHandleDescr_t *recv_handle, size_t requested_size, size_t *received_size, uint8_t *bytes, uint64_t *arg, const timespec_t *timeout)

Receive data from the FLI adapter.

All receive operations between an open and a close of a recv handle are guaranteed to be received by one receiver in the order they were sent. If the return code comes comes back with DRAGON_EOT, then there is no more data to be received. When DRAGON_EOT is returned there may be valid data with it. The num_bytes will always indicate the amount of valid data returned.

Parameters:

recv_handle – is an open send handle.
requested_size – is the maximum number of bytes to receive. There may be less bytes received. num_bytes provides the actual number of bytes read. If requested_size==0 then all available bytes are read.
received_size – is a pointer to a variable that will be initialized with the number of received bytes.
bytes – is a pointer that points to space at least of requested_size. This is provided by the caller of this function and will be filled in with received_size bytes upon successful completion of this call.
arg – is a pointer to meta-data assigned in a 64-bit unsigned integer by the sender when the data was sent. If NULL is provided, the arg is not returned.
timeout – is a pointer to a timeout structure. If NULL, then wait forever with no timeout. If not NULL, then wait for the specified amount of time and return DRAGON_TIMEOUT if not sucessful. If 0,0 is provided, then that indicates that a try-once attempt is to be made.

Returns:

DRAGON_SUCCESS, DRAGON_EOT or a return code to indicate what problem occurred. When DRAGON_EOT is returned there may also be bytes that were read or there may be zero bytes read.

dragonError_t dragon_fli_recv_mem(dragonFLIRecvHandleDescr_t *recv_handle, dragonMemoryDescr_t *mem, uint64_t *arg, const timespec_t *timeout)

Receive a Memory Descriptor from the FLI adapter.

All receive operations between an open and a close of a recv handle are guaranteed to be received by one receiver in the order they were sent. This operation is a lower-level receive operation that returns the memory descriptor that was read from the channel.

Parameters:

recv_handle – is an open receive handle.
mem – is a memory descriptor that will be initialized (upon DRAGON_SUCCESS completion) with the shared memory where the message is located.
arg – is a pointer to meta-data assigned in a 64-bit unsigned integer by the sender when the data was sent. If NULL is provided, the arg is not returned.
timeout – is a pointer to a timeout structure. If NULL, then wait forever with no timeout. If not NULL, then wait for the specified amount of time and return DRAGON_TIMEOUT if not sucessful. If 0,0 is provided, then that indicates that a try-once attempt is to be made.

Returns:

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

dragonError_t dragon_fli_poll(const dragonFLIDescr_t *adapter, const timespec_t *timeout)

Poll the main channel from the FLI adapter.

Parameters:

adapter – is a descriptor and opaque handle to the FLI adapter.
timeout – is a pointer to a timeout structure. If NULL, then wait forever with no timeout. If not NULL, then wait for the specified amount of time and return DRAGON_TIMEOUT if not sucessful. If 0,0 is provided, then that indicates that a try-once attempt is to be made.

Returns:

DRAGON_SUCCESS if there was at least one message in the main channel. DRAGON_EMPTY if there was no messages.

dragonError_t dragon_fli_full(const dragonFLIDescr_t *adapter)

Check if the main channel is full from the FLI adapter.

Parameters:: adapter – is a descriptor and opaque handle to the FLI adapter.
Returns:: DRAGON_SUCCESS if the main channel is full, otherwise return DRAGON_NOT_FULL.

dragonError_t dragon_fli_num_msgs(const dragonFLIDescr_t *adapter, size_t *num_msgs, const timespec_t *timeout)

Get the number of messages in the main channel from the FLI adapter.

Parameters:

adapter – is a descriptor and opaque handle to the FLI adapter.
num_msgs – is a pointer that holds the value of number of messages in the main channel.
timeout – is a pointer to a timeout structure. If NULL, then wait forever with no timeout. If not NULL, then wait for the specified amount of time and return DRAGON_TIMEOUT if not sucessful. If 0,0 is provided, then that indicates that a try-once attempt is to be made.

Returns:

DRAGON_SUCESS or a return code to indicate what problem occurred.