The BMI interface can be separated into categories as follows: message
initiation, message testing, memory management, list I/O, and utilities.
The message initiation functions are used by an application to
request the sending or receiving of network buffers:
- BMI_post_send(): Posts a send operation.
- BMI_post_recv(): Posts a receive operation.
- BMI_post_sendunexpected(): Posts a send operation
that was not expected by the receiving process.
- BMI_unpost(): Unposts a previously submitted
operation. This is a blocking call.
- BMI_addr_lookup(): Converts the string
representation of a BMI address (in url-like form) into an opaque
BMI addr type.
The message testing functions are used to check for completion of
network operations:
- BMI_test(): Tests for completion of a single
operation.
- BMI_testsome(): Tests for completion of any of a
specified set of operations.
- BMI_testunexpected(): Tests for arrival of any
unexpected messages.
- BMI_wait(): Tests for completion of a single
operation; is allowed to block briefly if no work is available.
- BMI_waitsome(): Tests for completion of any of a
specified set of operations; is allowed to block briefly if no
work is available.
- BMI_waitunexpected(): Tests for completion of any
of a specified set of operations; is allowed to block briefly if
no work is available.
The BMI memory management functions are used to control memory buffers
that are optimized for use with BMI:
- BMI_memalloc(): Creates a new buffer.
- BMI_memfree(): Destroys a buffer previously
created with BMI_memalloc().
The list I/O functions are very similar to the message initiation
functions. However, they allow the caller to express buffers as
arrays of discontiguous regions
Note that each of these functions requires the caller to pass in
an array of pointers and sizes to use as I/O targets. These
arrays must not be freed or modified until completion of the
requested operation (they are not copied by the BMI interface).
- BMI_post_send_list(): Same as BMI_post_send,
except that it allows the caller to specify an array of buffers
and sizes to send from.
- BMI_post_recv_list(): Same as BMI_post_recv,
except that it allows the caller to specify an array of buffers
and sizes to receive into.
- BMI_post_sendunexpected_list(): Same as
BMI_post_sendunexpected(), execept that it allows the caller to
specify an array of buffers and sizes to send from.
The final collection of functions perform various utility tasks that are
not directly involved in network I/O:
- BMI_initialize(): Starts the BMI interface; must
be called prior to any other BMI functions.
- BMI_finalize(): Shuts down the BMI interface.
- BMI_set_info(): Sets optional BMI parameters.
- BMI_get_info(): Reads optional BMI parameters.
Subsections