.TH "fi_trigger" "3" "2017\-02\-16" "Libfabric Programmer\[aq]s Manual" "\@VERSION\@" .SH NAME .PP fi_trigger \- Triggered operations .SH SYNOPSIS .IP .nf \f[C] #include\ \f[] .fi .SH DESCRIPTION .PP Triggered operations allow an application to queue a data transfer request that is deferred until a specified condition is met. A typical use is to send a message only after receiving all input data. .PP A triggered operation may be requested by specifying the FI_TRIGGER flag as part of the operation. Alternatively, an endpoint alias may be created and configured with the FI_TRIGGER flag. Such an endpoint is referred to as a trigger\-able endpoint. All data transfer operations on a trigger\-able endpoint are deferred. .PP Any data transfer operation is potentially trigger\-able, subject to provider constraints. Trigger\-able endpoints are initialized such that only those interfaces supported by the provider which are trigger\-able are available. .PP Triggered operations require that applications use struct fi_triggered_context as their per operation context parameter. The use of struct fi_triggered_context replaces struct fi_context, if required by the provider. Although struct fi_triggered_context is not opaque to the application, the contents of the structure may be modified by the provider. This structure has similar requirements as struct fi_context. It must be allocated by the application and remain valid until the corresponding operation completes or is successfully canceled. .PP Struct fi_triggered_context is used to specify the condition that must be met before the triggered data transfer is initiated. If the condition is met when the request is made, then the data transfer may be initiated immediately. The format of struct fi_triggered_context is described below. .IP .nf \f[C] struct\ fi_triggered_context\ { \ \ \ \ enum\ fi_trigger_event\ \ \ event_type;\ \ \ /*\ trigger\ type\ */ \ \ \ \ union\ { \ \ \ \ \ \ \ \ struct\ fi_trigger_threshold\ threshold; \ \ \ \ \ \ \ \ void\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ *internal[3];\ /*\ reserved\ */ \ \ \ \ }\ trigger; }; \f[] .fi .PP The triggered context indicates the type of event assigned to the trigger, along with a union of trigger details that is based on the event type. .SS TRIGGER EVENTS .PP The following trigger events are defined. .PP \f[I]FI_TRIGGER_THRESHOLD\f[] : This indicates that the data transfer operation will be deferred until an event counter crosses an application specified threshold value. The threshold is specified using struct fi_trigger_threshold: .PP \f[C]c\ \ \ struct\ fi_trigger_threshold\ {\ \ \ \ \ struct\ fid_cntr\ *cntr;\ /*\ event\ counter\ to\ check\ */\ \ \ \ \ size_t\ threshold;\ \ \ \ \ \ /*\ threshold\ value\ */\ \ \ };\f[] .PP Threshold operations are triggered in the order of the threshold values. This is true even if the counter increments by a value greater than 1. If two triggered operations have the same threshold, they will be triggered in the order in which they were submitted to the endpoint. .SH EXPERIMENTAL TRIGGERED OPERATIONS .PP The following feature and description are enhancements to triggered operation support, but should be considered experimental. Until the experimental tag is removed, the interfaces and data structures defined below may change between library versions. .PP Experimental triggered operations allow an application to queue operations to a deferred work queue that is associated with the domain. Note that the deferred work queue is a conceptual construct, rather than an implementation requirement. Deferred work requests consist of two components: an event or condition that must first be met, along with an operation to perform. .PP Because deferred work requests are posted directly to the domain, they can support a broader set of conditions and operations. Deferred work requests are submitted using struct fi_deferred_work. That structure, along with any event and operation structures used to describe the work must remain valid until the operation completes or is canceled. .IP .nf \f[C] struct\ fi_deferred_work\ { \ \ \ \ struct\ fi_context\ \ \ \ \ context; \ \ \ \ enum\ fi_trigger_event\ event_type; \ \ \ \ enum\ fi_trigger_op\ \ \ \ op_type; \ \ \ \ union\ { \ \ \ \ \ \ \ \ struct\ fi_trigger_threshold\ *threshold; \ \ \ \ \ \ \ \ struct\ fi_trigger_completion\ *completion; \ \ \ \ }\ event; \ \ \ \ union\ { \ \ \ \ \ \ \ \ struct\ fi_op_msg\ \ \ \ \ \ \ \ \ \ \ \ *msg; \ \ \ \ \ \ \ \ struct\ fi_op_tagged\ \ \ \ \ \ \ \ \ *tagged; \ \ \ \ \ \ \ \ struct\ fi_op_rma\ \ \ \ \ \ \ \ \ \ \ \ *rma; \ \ \ \ \ \ \ \ struct\ fi_op_atomic\ \ \ \ \ \ \ \ \ *atomic; \ \ \ \ \ \ \ \ struct\ fi_op_fetch_atomic\ \ \ *fetch_atomic; \ \ \ \ \ \ \ \ struct\ fi_op_compare_atomic\ *compare_atomic; \ \ \ \ \ \ \ \ struct\ fi_op_cntr\ \ \ \ \ \ \ \ \ \ \ *cntr; \ \ \ \ }\ op; }; \f[] .fi .PP Once a work request has been posted to the deferred work queue, it will remain on the queue until its condition has been met. It is the responsibility of the application to detect and handle situations that occur which could result in the condition not being met. For example, if a work request is dependent upon the successful completion of a data transfer operation, which fails, then the application must cancel the work request. A work request with its condition met at the time of posting will automatically have its operation initiated. .PP If the work request will generate a completion, the completion event will return the context field of struct fi_deferred_work as the context for the operation. .PP To submit a deferred work request, applications should use the domain\[aq]s fi_control function with command FI_QUEUE_WORK and struct fi_deferred_work as the fi_control arg parameter. To cancel a deferred work request, use fi_control with command FI_CANCEL_WORK and the corresponding struct fi_deferred_work to cancel. The fi_control command FI_FLUSH_WORK will cancel all queued work requests. .PP Deferred work requests are not acted upon by the provider until the associated event has occurred; although, certain validation checks may still occur when a request is submitted. Referenced data buffers are not read or otherwise accessed. But the provider may validate fabric objects, such as endpoints and counters, and that input parameters fall within supported ranges. If a specific request is not supported by the provider, it will fail the operation with \-FI_ENOSYS. .SS EXPERIMENTAL TRIGGER EVENTS .PP The following trigger events are defined. .PP \f[I]FI_TRIGGER_THRESHOLD\f[] : See the above definition. .PP \f[I]FI_TRIGGER_COMPLETION\f[] : This indicates that the data transfer operation will be deferred until the specified operation has completed. The operation is specified using struct fi_trigger_completion: .PP \f[C]c\ \ \ struct\ fi_trigger_completion\ {\ \ \ \ \ struct\ fi_context\ *context;\ \ \ };\f[] .PP The context must refer to the fi_context of the posted operation. .SH SEE ALSO .PP \f[C]fi_getinfo\f[](3), \f[C]fi_endpoint\f[](3), \f[C]fi_alias\f[](3), \f[C]fi_cntr\f[](3) .SH AUTHORS OpenFabrics.