fi_cntr(3) | @VERSION@ | fi_cntr(3) |
fi_cntr - Completion and event counter operations
#include <rdma/fi_domain.h> int fi_cntr_open(struct fid_domain *domain, struct fi_cntr_attr *attr, struct fid_cntr **cntr, void *context); int fi_close(struct fid *cntr); uint64_t fi_cntr_read(struct fid_cntr *cntr); uint64_t fi_cntr_readerr(struct fid_cntr *cntr); int fi_cntr_add(struct fid_cntr *cntr, uint64_t value); int fi_cntr_adderr(struct fid_cntr *cntr, uint64_t value); int fi_cntr_set(struct fid_cntr *cntr, uint64_t value); int fi_cntr_seterr(struct fid_cntr *cntr, uint64_t value); int fi_cntr_wait(struct fid_cntr *cntr, uint64_t threshold, int timeout);
Counters record the number of requested operations that have completed. Counters can provide a light-weight completion mechanism by allowing the suppression of CQ completion entries. They are useful for applications that only need to know the number of requests that have completed, and not details about each request. For example, counters may be useful for implementing credit based flow control or tracking the number of remote processes that have responded to a request.
Counters typically only count successful completions. However, if an operation completes in error, it may increment an associated error value. That is, a counter actually stores two distinct values, with error completions updating an error specific value.
Counters are updated following the completion event semantics defined in fi_cq(3). The timing of the update is based on the type of transfer and any specified operation flags.
fi_cntr_open allocates a new fabric counter. The properties and behavior of the counter are defined by struct fi_cntr_attr.
struct fi_cntr_attr { enum fi_cntr_events events; /* type of events to count */ enum fi_wait_obj wait_obj; /* requested wait object */ struct fid_wait *wait_set; /* optional wait set */ uint64_t flags; /* operation flags */ };
The fi_close call releases all resources associated with a counter. When closing the counter, there must be no opened endpoints, transmit contexts, receive contexts or memory regions associated with the counter. If resources are still associated with the counter when attempting to close, the call will return -FI_EBUSY.
The fi_cntr_control call is used to access provider or implementation specific details of the counter. Access to the counter should be serialized across all calls when fi_cntr_control is invoked, as it may redirect the implementation of counter operations. The following control commands are usable with a counter:
The fi_cntr_read call returns the current value of the counter.
The read error call returns the number of operations that completed in error and were unable to update the counter.
This adds the user-specified value to the counter.
This adds the user-specified value to the error value of the counter.
This sets the counter to the specified value.
This sets the error value of the counter to the specified value.
This call may be used to wait until the counter reaches the specified threshold, or until an error or timeout occurs. Upon successful return from this call, the counter will be greater than or equal to the input threshold value.
If an operation associated with the counter encounters an error, it will increment the error value associated with the counter. Any change in a counter's error value will unblock any thread inside fi_cntr_wait.
If the call returns due to timeout, -FI_ETIMEDOUT will be returned. The error value associated with the counter remains unchanged.
It is invalid for applications to call this function if the counter has been configured with a wait object of FI_WAIT_NONE or FI_WAIT_SET.
Returns 0 on success. On error, a negative value corresponding to fabric errno is returned.
Fabric errno values are defined in rdma/fi_errno.h.
In order to support a variety of counter implementations, updates made to counter values (e.g. fi_cntr_set or fi_cntr_add) may not be immediately visible to counter read operations (i.e. fi_cntr_read or fi_cntr_readerr). A small, but undefined, delay may occur between the counter changing and the reported value being updated. However, a final updated value will eventually be reflected in the read counter value.
Additionally, applications should ensure that the value of a counter is stable and not subject to change prior to calling fi_cntr_set or fi_cntr_seterr. Otherwise, the resulting value of the counter after fi_cntr_set / fi_cntr_seterr is undefined, as updates to the counter may be lost. A counter value is considered stable if all previous updates using fi_cntr_set / fi_cntr_seterr and results of related operations are reflected in the observed value of the counter.
fi_getinfo(3), fi_endpoint(3), fi_domain(3), fi_eq(3), fi_poll(3)
OpenFabrics.
2019-12-13 | Libfabric Programmer's Manual |