Commit 571c52bc authored by Matthieu Dorier's avatar Matthieu Dorier
Browse files

added comments

parent 9c73b20d
......@@ -44,102 +44,354 @@ mona_instance_t mona_init_na_pool(
na_context_t *na_context,
ABT_pool progress_pool);
/**
* Finalize the Mona instance. If operations are still
* pending (e.g. from other threads), this function will
* block until they are completed.
*
* \param mona [IN/OUT] Mona instance
*
* \return NA_SUCCESS or corresponding NA error code
*/
na_return_t mona_finalize(mona_instance_t mona);
/**
* Return the name of the Mona instance's underlying NA class.
*
* \param mona [IN] Mona instance
*
* \return Pointer to NA class name or NULL in case of failure
*/
const char* mona_get_class_name(mona_instance_t mona);
/**
* Return the protocol of the Mona instance's underlying NA class.
*
* \param mona [IN] Mona instance
*
* \return Pointer to NA class protocol or NULL in case of failure
*/
const char* mona_get_class_protocol(mona_instance_t mona);
/**
* Test whether the Mona instance is listening or not.
*
* \param mona [IN] Mona instance
*
* \return NA_TRUE if listening or NA_FALSE if not
*/
na_bool_t mona_is_listening(mona_instance_t mona);
/**
* Lookup an addr from a peer address/name. Addresses need to be
* freed by calling mona_addr_free().
*
* \param mona [IN/OUT] Mona instance
* \param name [IN] lookup name
* \param addr [OUT] pointer to abstract address
*
* \return NA_SUCCESS or corresponding NA error code
*/
na_return_t mona_addr_lookup(
mona_instance_t mona,
const char *name,
na_addr_t *addr);
/**
* Free the addr from the list of peers.
*
* \param mona [IN/OUT] Mona instance
* \param addr [IN] abstract address
*
* \return NA_SUCCESS or corresponding NA error code
*/
na_return_t mona_addr_free(
mona_instance_t mona,
na_addr_t addr);
/**
* Hint that the address is no longer valid. This may happen if the peer is
* no longer responding. This can be used to force removal of the
* peer address from the list of the peers, before freeing it and reclaim
* resources.
*
* \param mona [IN/OUT] Mona instance
* \param addr [IN] abstract address
*
* \return NA_SUCCESS or corresponding NA error code
*/
na_return_t mona_addr_set_remove(
mona_instance_t mona,
na_addr_t addr);
/**
* Access self address.
*
* \param mona [IN/OUT] Mona instance
* \param addr [OUT] pointer to abstract address
*
* \return NA_SUCCESS or corresponding NA error code
*/
na_return_t mona_addr_self(
mona_instance_t mona,
na_addr_t* addr);
/**
* Duplicate an existing NA abstract address. The duplicated address can be
* stored for later use and the origin address be freed safely. The duplicated
* address must be freed with mona_addr_free().
*
* \param mona [IN/OUT] Mona instance
* \param addr [IN] abstract address
* \param new_addr [OUT] pointer to abstract address
*
* \return NA_SUCCESS or corresponding NA error code
*/
na_return_t mona_addr_dup(
mona_instance_t mona,
na_addr_t addr,
na_addr_t* dup_addr);
/**
* Compare two addresses.
*
* \param mona [IN/OUT] Mona instance
* \param addr1 [IN] abstract address
* \param addr2 [IN] abstract address
*
* \return NA_TRUE if addresses are determined to be equal, NA_FALSE otherwise
*/
na_bool_t mona_addr_cmp(
mona_instance_t mona,
na_addr_t addr1,
na_addr_t addr2);
/**
* Test whether address is self or not.
*
* \param mona[IN/OUT] Mona instance
* \param addr [IN] abstract address
*
* \return NA_TRUE if self or NA_FALSE if not
*/
na_bool_t mona_addr_is_self(
mona_instance_t mona,
na_addr_t addr);
/**
* Convert an addr to a string (returned string includes the terminating
* null byte '\0'). If buf is NULL, the address is not converted and only
* the required size of the buffer is returned. If the input value passed
* through buf_size is too small, NA_SIZE_ERROR is returned and the buf_size
* output is set to the minimum size required.
*
* \param mona [IN/OUT] Mona instance
* \param buf [IN/OUT] pointer to destination buffer
* \param buf_size [IN/OUT] pointer to buffer size
* \param addr [IN] abstract address
*
* \return NA_SUCCESS or corresponding NA error code
*/
na_return_t mona_addr_to_string(
mona_instance_t mona,
char *buf,
na_size_t *buf_size,
na_addr_t addr);
/**
* Get size required to serialize address.
*
* \param mona [IN/OUT] Mona instance
* \param addr [IN] abstract address
*
* \return Non-negative value
*/
na_size_t mona_addr_get_serialize_size(
mona_instance_t mona,
na_addr_t addr);
/**
* Serialize address into a buffer.
*
* \param mona [IN/OUT] Mona instance
* \param buf [IN/OUT] pointer to buffer used for serialization
* \param buf_size [IN] buffer size
* \param addr [IN] abstract address
*
* \return NA_SUCCESS or corresponding NA error code
*/
na_return_t mona_addr_serialize(
mona_instance_t mona,
void *buf,
na_size_t buf_size,
na_addr_t addr);
/**
* Deserialize address from a buffer. The returned address must be freed with
* mona addr_free().
*
* \param mona [IN/OUT] Mona instance
* \param addr [OUT] pointer to abstract address
* \param buf [IN] pointer to buffer used for deserialization
* \param buf_size [IN] buffer size
*
* \return NA_SUCCESS or corresponding NA error code
*/
na_return_t mona_addr_deserialize(
mona_instance_t mona,
na_addr_t *addr,
const void *buf,
na_size_t buf_size);
/**
* Get the maximum size of messages supported by unexpected send/recv.
* Small message size.
*
* \param mona [IN] Mona instance
*
* \return Non-negative value
*/
na_size_t mona_msg_get_max_unexpected_size(
mona_instance_t mona);
/**
* Get the maximum size of messages supported by expected send/recv.
* Small message size that may differ from the unexpected message size.
*
* \param mona [IN] Mona instance
*
* \return Non-negative value
*/
na_size_t mona_msg_get_max_expected_size(
mona_instance_t mona);
/**
* Get the header size for unexpected messages. Plugins may use that header
* to encode specific information (such as source addr, etc).
*
* \param mona [IN] Mona instance
*
* \return Non-negative value
*/
na_size_t mona_msg_get_unexpected_header_size(
mona_instance_t mona);
/**
* Get the header size for expected messages. Plugins may use that header
* to encode specific information.
*
* \param mona [IN] Mona instance
*
* \return Non-negative value
*/
na_size_t mona_msg_get_expected_header_size(
mona_instance_t mona);
/**
* Get the maximum tag value that can be used by send/recv (both expected and
* unexpected).
*
* \param mona [IN] Mona instance
*
* \return Non-negative value
*/
na_tag_t mona_msg_get_max_tag(mona_instance_t mona);
/**
* Allocate an operation ID to be used for isend, irecv, iput, and iget operations.
* Allocating an operation ID gives ownership of that ID to the higher level
* layer, hence it must be explicitly released with mona_op_destroy() when it
* is no longer needed.
*
* \param mona [IN/OUT] Mona instance
*
* \return valid operation ID or NA_OP_ID_NULL
*/
na_op_id_t mona_op_create(mona_instance_t mona);
/**
* Destroy operation ID created with mona_op_create().
* Reference counting prevents involuntary free.
*
* \param mona [IN/OUT] Mona instance
* \param op_id [IN] operation ID
*
* \return NA_SUCCESS or corresponding NA error code
*/
na_return_t mona_op_destroy(
mona_instance_t mona,
na_op_id_t op_id);
/**
* Allocate buf_size bytes and return a pointer to the allocated memory.
* If size is 0, mona_msg_buf_alloc() returns NULL. The plugin_data output
* parameter can be used by the underlying plugin implementation to store
* internal memory information.
*
* \param mona [IN/OUT] Mona instance
* \param buf_size [IN] buffer size
* \param plugin_data [OUT] pointer to internal plugin data
*
* \return Pointer to allocated memory or NULL in case of failure
*/
void* mona_msg_buf_alloc(
mona_instance_t mona,
na_size_t buf_size,
void **plugin_data);
/**
* The mona_msg_buf_free() function releases the memory space pointed to by buf,
* which must have been returned by a previous call to mona_msg_buf_alloc().
* If buf is NULL, no operation is performed.
*
* \param mona [IN/OUT] Mona instance
* \param buf [IN] pointer to buffer
* \param plugin_data [IN] pointer to internal plugin data
*
* \return NA_SUCCESS or corresponding NA error code
*/
na_return_t mona_msg_buf_free(
mona_instance_t mona,
void *buf,
void *plugin_data);
/**
* Initialize a buffer so that it can be safely passed to the
* mona_msg_send_unexpected() call. In the case the underlying plugin adds its
* own header to that buffer, the header will be written at this time and the
* usable buffer payload will be buf + mona_msg_get_unexpected_header_size().
*
* \param mona [IN/OUT] Mona instance
* \param buf [IN] pointer to buffer
* \param buf_size [IN] buffer size
*
* \return NA_SUCCESS or corresponding NA error code
*/
na_return_t mona_msg_init_unexpected(
mona_instance_t mona,
void *buf,
na_size_t buf_size);
/**
* Send an unexpected message to dest_addr. Unexpected sends do not require a
* matching receive to complete.
* The plugin_data parameter returned from the mona_msg_buf_alloc() call must
* be passed along with the buffer, it allows plugins to store and retrieve
* additional buffer information such as memory descriptors.
* \remark Note also that unexpected messages do not require an unexpected
* receive to be posted at the destination before sending the message and the
* destination is allowed to drop the message without notification.
*
* \param mona [IN/OUT] Mona instance
* \param buf [IN] pointer to send buffer
* \param buf_size [IN] buffer size
* \param plugin_data [IN] pointer to internal plugin data
* \param dest_addr [IN] abstract address of destination
* \param dest_id [IN] destination context ID
* \param tag [IN] tag attached to message
*
* \return NA_SUCCESS or corresponding NA error code
*/
na_return_t mona_msg_send_unexpected(
mona_instance_t mona,
const void *buf,
......@@ -149,6 +401,32 @@ na_return_t mona_msg_send_unexpected(
na_uint8_t dest_id,
na_tag_t tag);
/**
* Send an unexpected message to dest_addr, without blocking. Unexpected
* sends do not require a matching receive to complete. The resulting
* mona_request_t must be waited on using mona_wait().
* The plugin_data parameter returned from the mona_msg_buf_alloc() call must
* be passed along with the buffer, it allows plugins to store and retrieve
* additional buffer information such as memory descriptors.
* \remark Note also that unexpected messages do not require an unexpected
* receive to be posted at the destination before sending the message and the
* destination is allowed to drop the message without notification.
*
* The user is responsible for creating a new operation id using mona_op_create()
* before calling this function, and destroy it after using mona_op_destroy.
*
* \param mona [IN/OUT] Mona instance
* \param buf [IN] pointer to send buffer
* \param buf_size [IN] buffer size
* \param plugin_data [IN] pointer to internal plugin data
* \param dest_addr [IN] abstract address of destination
* \param dest_id [IN] destination context ID
* \param tag [IN] tag attached to message
* \param op_id [IN] operation ID
* \param req [OUT] request tracking operation completion
*
* \return NA_SUCCESS or corresponding NA error code
*/
na_return_t mona_msg_isend_unexpected(
mona_instance_t mona,
const void *buf,
......@@ -157,9 +435,30 @@ na_return_t mona_msg_isend_unexpected(
na_addr_t dest_addr,
na_uint8_t dest_id,
na_tag_t tag,
na_op_id_t *op_id,
na_op_id_t* op_id,
mona_request_t* req);
/**
* Receive an unexpected message. Unexpected receives may wait on any tag and
* any source depending on the implementation.
* The plugin_data parameter returned from the mona_msg_buf_alloc() call must
* be passed along with the buffer, it allows plugins to store and retrieve
* additional buffer information such as memory descriptors.
*
* The source_addr, tag, and size arguments may be NULL. If source_addr
* is not NULL, the sender's address will be duplicated into it. It is
* the caller's responsibility to free it using mona_addr_free().
*
* \param mona [IN/OUT] Mona instance
* \param buf [IN] pointer to send buffer
* \param buf_size [IN] buffer size
* \param plugin_data [IN] pointer to internal plugin data
* \param source_addr [OUT] address of the sender
* \param tag [OUT] tag used by the sender
* \param size [OUT] actual size of the data received
*
* \return NA_SUCCESS or corresponding NA error code
*/
na_return_t mona_msg_recv_unexpected(
mona_instance_t mona,
void *buf,
......@@ -168,7 +467,30 @@ na_return_t mona_msg_recv_unexpected(
na_addr_t* source_addr,
na_tag_t* tag,
na_size_t* size);
/**
* Receive an unexpected message in an non-blocking manner. Unexpected receives
* may wait on any tag and any source depending on the implementation.
* The plugin_data parameter returned from the mona_msg_buf_alloc() call must
* be passed along with the buffer, it allows plugins to store and retrieve
* additional buffer information such as memory descriptors.
*
* The user is responsible for creating a new operation id using mona_op_create()
* before calling this function, and destroy it after using mona_op_destroy.
*
* \param mona [IN/OUT] Mona instance
* \param callback [IN] pointer to function callback
* \param arg [IN] pointer to data passed to callback
* \param buf [IN] pointer to send buffer
* \param buf_size [IN] buffer size
* \param plugin_data [IN] pointer to internal plugin data
* \param source_addr [OUT] address of the sender
* \param tag [OUT] tag used by the sender
* \param size [OUT] actual size of the data received
* \param op_id [IN] operation ID
* \param req [OUT] request tracking operation completion
*
* \return NA_SUCCESS or corresponding NA error code
*/
na_return_t mona_msg_irecv_unexpected(
mona_instance_t mona,
void *buf,
......@@ -177,14 +499,46 @@ na_return_t mona_msg_irecv_unexpected(
na_addr_t* source_addr,
na_tag_t* tag,
na_size_t* size,
na_op_id_t *op_id,
na_op_id_t* op_id,
mona_request_t* req);
/**
* Initialize a buffer so that it can be safely passed to the
* mona_msg_send_expected() call. In the case the underlying plugin adds its
* own header to that buffer, the header will be written at this time and the
* usable buffer payload will be buf + mona_msg_get_expected_header_size().
*
* \param mona [IN/OUT] Mona instance
* \param buf [IN] pointer to buffer
* \param buf_size [IN] buffer size
*
* \return NA_SUCCESS or corresponding NA error code
*/
na_return_t mona_msg_init_expected(
mona_instance_t mona,
void *buf,
na_size_t buf_size);
/**
* Send an expected message to dest_addr.
* The plugin_data parameter returned from the mona_msg_buf_alloc() call must
* be passed along with the buffer, it allows plugins to store and retrieve
* additional buffer information such as memory descriptors.
* \remark Note that expected messages require an expected receive to be posted
* at the destination before sending the message, otherwise the destination is
* allowed to drop the message without notification.
*
* \param mona [IN/OUT] Mona instance
* \param buf [IN] pointer to send buffer
* \param buf_size [IN] buffer size
* \param plugin_data [IN] pointer to internal plugin data
* \param dest_addr [IN] abstract address of destination
* \param dest_id [IN] destination context ID
* \param tag [IN] tag attached to message
*
* \return NA_SUCCESS or corresponding NA error code
*/
na_return_t mona_msg_send_expected(
mona_instance_t mona,
const void *buf,
......@@ -194,6 +548,30 @@ na_return_t mona_msg_send_expected(
na_uint8_t dest_id,
na_tag_t tag);
/**
* Send an expected message to dest_addr in a non-blocking manner.
* The plugin_data parameter returned from the mona_msg_buf_alloc() call must
* be passed along with the buffer, it allows plugins to store and retrieve
* additional buffer information such as memory descriptors.
* \remark Note that expected messages require an expected receive to be posted
* at the destination before sending the message, otherwise the destination is
* allowed to drop the message without notification.
*
* The user is responsible for creating a new operation id using mona_op_create()
* before calling this function, and destroy it after using mona_op_destroy.
*
* \param mona [IN/OUT] Mona instance
* \param buf [IN] pointer to send buffer
* \param buf_size [IN] buffer size
* \param plugin_data [IN] pointer to internal plugin data
* \param dest_addr [IN] abstract address of destination
* \param dest_id [IN] destination context ID
* \param tag [IN] tag attached to message
* \param op_id [IN] operation ID
* \param req [OUT] request tracking operation completion
*
* \return NA_SUCCESS or corresponding NA error code
*/
na_return_t mona_msg_isend_expected(
mona_instance_t mona,
const void *buf,
......@@ -202,9 +580,25 @@ na_return_t mona_msg_isend_expected(
na_addr_t dest_addr,
na_uint8_t dest_id,
na_tag_t tag,
na_op_id_t *op_id,
na_op_id_t* op_id,
mona_request_t* req);
/**
* Receive an expected message from source_addr.
* The plugin_data parameter returned from the mona_msg_buf_alloc() call must
* be passed along with the buffer, it allows plugins to store and retrieve
* additional buffer information such as memory descriptors.
*
* \param mona [IN/OUT] Mona instance
* \param buf [IN] pointer to receive buffer
* \param buf_size [IN] buffer size
* \param plugin_data [IN] pointer to internal plugin data
* \param source_addr [IN] abstract address of source
* \param source_id [IN] source context ID
* \param tag [IN] matching tag used to receive message
*
* \return NA_SUCCESS or corresponding NA error code
*/
na_return_t mona_msg_recv_expected(
mona_instance_t mona,
void *buf,
......@@ -214,6 +608,27 @@ na_return_t mona_msg_recv_expected(
na_uint8_t source_id,
na_tag_t tag);
/**
* Receive an expected message from source_addr in a non-blocking mannger.
* The plugin_data parameter returned from the mona_msg_buf_alloc() call must
* be passed along with the buffer, it allows plugins to store and retrieve
* additional buffer information such as memory descriptors.
*
* The user is responsible for creating a new operation id using mona_op_create()
* before calling this function, and destroy it after using mona_op_destroy.
*
* \param mona [IN/OUT] Mona instance
* \param buf [IN] pointer to receive buffer
* \param buf_size [IN] buffer size
* \param plugin_data [IN] pointer to internal plugin data
* \param source_addr [IN] abstract address of source
* \param source_id [IN] source context ID
* \param tag [IN] matching tag used to receive message
* \param op_id [IN] operation ID
* \param req [OUT] request tracking operation completion
*
* \return NA_SUCCESS or corresponding NA error code
*/
na_return_t mona_msg_irecv_expected(
mona_instance_t mona,
void *buf,
......@@ -222,9 +637,26 @@ na_return_t mona_msg_irecv_expected(
na_addr_t source_addr,
na_uint8_t source_id,
na_tag_t tag,
na_op_id_t *op_id,
na_op_id_t* op_id,
mona_request_t* req);
/**
* Create memory handle for RMA operations.
* For non-contiguous memory, use mona_mem_handle_create_segments() instead.
*
* \remark Note to plugin developers: mona_mem_handle_create() may be called
* multiple times on the same memory region.
*
* \param mona [IN/OUT] Mona instance
* \param buf [IN] pointer to buffer that needs to be registered
* \param buf_size [IN] buffer size
* \param flags [IN] permission flag:
* - NA_MEM_READWRITE
* - NA_MEM_READ_ONLY
* \param mem_handle [OUT] pointer to returned abstract memory handle
*
* \return NA_SUCCESS or corresponding NA error code
*/
na_return_t mona_mem_handle_create(
mona_instance_t mona,
void *buf,
......@@ -232,6 +664,25 @@ na_return_t mona_mem_handle_create(
unsigned long flags,
na_mem_handle_t *mem_handle);
/**
* Create memory handle for RMA operations.
* Create_segments can be used to register fragmented pieces and get a single
* memory handle.
* \remark Implemented only if the network transport or hardware supports it.
*
* \param mona [IN/OUT] Mona instance
* \param segments [IN] pointer to array of segments composed of:
* - address of the segment that needs to be
* registered
* - size of the segment in bytes
* \param segment_count [IN] segment count
* \param flags [IN] permission flag:
* - NA_MEM_READWRITE
* - NA_MEM_READ_ONLY
* \param mem_handle [OUT] pointer to returned abstract memory handle
*
* \return NA_SUCCESS or corresponding NA error code
*/
na_return_t mona_mem_handle_create_segments(
mona_instance_t mona,
struct na_segment *segments,
......@@ -239,41 +690,134 @@ na_return_t mona_mem_handle_create_segments(
unsigned long flags,
na_mem_handle_t *mem_handle);
/**
* Free memory handle.
*
* \param mona [IN/OUT] Mona instance
* \param mem_handle [IN] abstract memory handle
*
* \return NA_SUCCESS or corresponding NA error code
*/
na_return_t mona_mem_handle_free(
mona_instance_t mona,
na_mem_handle_t mem_handle);
/**
* Register memory for RMA operations.
* Memory pieces must be registered before one-sided transfers can be
* initiated.