OpenMPI  0.1.1
request.h File Reference

Top-level description of requests. More...

#include "ompi_config.h"
#include "mpi.h"
#include "ompi/class/ompi_free_list.h"
#include "opal/class/opal_pointer_array.h"
#include "opal/threads/condition.h"
#include "ompi/constants.h"
#include "ompi/runtime/params.h"
#include "request_dbg.h"

Go to the source code of this file.

Data Structures

union  ompi_mpi_object_t
 Union for holding several different MPI pointer types on the request. More...
 
struct  ompi_request_t
 Main top-level request struct definition. More...
 
struct  ompi_predefined_request_t
 
struct  ompi_request_fns_t
 Replaceable request functions. More...
 

Macros

#define PREDEFINED_REQUEST_PAD   (sizeof(void*) * 32)
 Padded struct to maintain back compatibiltiy. More...
 
#define OMPI_REQUEST_INIT(request, persistent)
 Initialize a request. More...
 
#define OMPI_REQUEST_FINI(request)
 Finalize a request. More...
 
#define ompi_request_test   (ompi_request_functions.req_test)
 
#define ompi_request_test_any   (ompi_request_functions.req_test_any)
 
#define ompi_request_test_all   (ompi_request_functions.req_test_all)
 
#define ompi_request_test_some   (ompi_request_functions.req_test_some)
 
#define ompi_request_wait   (ompi_request_functions.req_wait)
 
#define ompi_request_wait_any   (ompi_request_functions.req_wait_any)
 
#define ompi_request_wait_all   (ompi_request_functions.req_wait_all)
 
#define ompi_request_wait_some   (ompi_request_functions.req_wait_some)
 
#define OMPI_STATUS_SET(outstat, instat)   (*(outstat) = *(instat))
 
#define OMPI_STATUS_SET_COUNT(outcount, incount)   (*(outcount) = *(incount))
 

Typedefs

typedef int(* ompi_request_free_fn_t )(struct ompi_request_t **rptr)
 
typedef int(* ompi_request_cancel_fn_t )(struct ompi_request_t *request, int flag)
 
typedef int(* ompi_request_complete_fn_t )(struct ompi_request_t *request)
 
typedef union ompi_mpi_object_t ompi_mpi_object_t
 Union for holding several different MPI pointer types on the request.
 
typedef struct ompi_request_t ompi_request_t
 Convenience typedef.
 
typedef struct
ompi_predefined_request_t 
ompi_predefined_request_t
 
typedef int(* ompi_request_test_fn_t )(ompi_request_t **rptr, int *completed, ompi_status_public_t *status)
 Non-blocking test for request completion. More...
 
typedef int(* ompi_request_test_any_fn_t )(size_t count, ompi_request_t **requests, int *index, int *completed, ompi_status_public_t *status)
 Non-blocking test for request completion. More...
 
typedef int(* ompi_request_test_all_fn_t )(size_t count, ompi_request_t **requests, int *completed, ompi_status_public_t *statuses)
 Non-blocking test for request completion. More...
 
typedef int(* ompi_request_test_some_fn_t )(size_t count, ompi_request_t **requests, int *outcount, int *indices, ompi_status_public_t *statuses)
 Non-blocking test for some of N requests to complete. More...
 
typedef int(* ompi_request_wait_fn_t )(ompi_request_t **req_ptr, ompi_status_public_t *status)
 Wait (blocking-mode) for one requests to complete. More...
 
typedef int(* ompi_request_wait_any_fn_t )(size_t count, ompi_request_t **requests, int *index, ompi_status_public_t *status)
 Wait (blocking-mode) for one of N requests to complete. More...
 
typedef int(* ompi_request_wait_all_fn_t )(size_t count, ompi_request_t **requests, ompi_status_public_t *statuses)
 Wait (blocking-mode) for all of N requests to complete. More...
 
typedef int(* ompi_request_wait_some_fn_t )(size_t count, ompi_request_t **requests, int *outcount, int *indices, ompi_status_public_t *statuses)
 Wait (blocking-mode) for some of N requests to complete. More...
 
typedef struct ompi_request_fns_t ompi_request_fns_t
 Replaceable request functions.
 

Functions

BEGIN_C_DECLS OMPI_DECLSPEC OBJ_CLASS_DECLARATION (ompi_request_t)
 Request class.
 
int ompi_request_init (void)
 Initialize the MPI_Request subsystem; invoked during MPI_INIT.
 
OMPI_DECLSPEC int ompi_request_persistent_proc_null_free (ompi_request_t **request)
 Free a persistent request to a MPI_PROC_NULL peer (there's no freelist to put it back to, so we have to actually OBJ_RELEASE it).
 
int ompi_request_finalize (void)
 Shut down the MPI_Request subsystem; invoked during MPI_FINALIZE.
 
static int ompi_request_cancel (ompi_request_t *request)
 Cancel a pending request.
 
static int ompi_request_free (ompi_request_t **request)
 Free a request. More...
 
static int ompi_request_complete (ompi_request_t *request, bool with_signal)
 Signal or mark a request as complete. More...
 
static void ompi_request_wait_completion (ompi_request_t *req)
 Wait a particular request for completion.
 

Variables

OMPI_DECLSPEC opal_pointer_array_t ompi_request_f_to_c_table
 Globals used for tracking requests and request completion.
 
OMPI_DECLSPEC size_t ompi_request_waiting
 
OMPI_DECLSPEC size_t ompi_request_completed
 
OMPI_DECLSPEC size_t ompi_request_failed
 
OMPI_DECLSPEC int32_t ompi_request_poll
 
OMPI_DECLSPEC opal_mutex_t ompi_request_lock
 
OMPI_DECLSPEC opal_condition_t ompi_request_cond
 
OMPI_DECLSPEC
ompi_predefined_request_t 
ompi_request_null
 
OMPI_DECLSPEC ompi_request_t ompi_request_empty
 
OMPI_DECLSPEC ompi_status_public_t ompi_status_empty
 
OMPI_DECLSPEC ompi_request_fns_t ompi_request_functions
 

Detailed Description

Top-level description of requests.

Macro Definition Documentation

#define OMPI_REQUEST_FINI (   request)
Value:
do { \
(request)->req_state = OMPI_REQUEST_INVALID; \
if (MPI_UNDEFINED != (request)->req_f_to_c_index) { \
(request)->req_f_to_c_index, NULL); \
(request)->req_f_to_c_index = MPI_UNDEFINED; \
} \
} while (0);
OMPI_DECLSPEC opal_pointer_array_t ompi_request_f_to_c_table
Globals used for tracking requests and request completion.
Definition: request.c:32
OPAL_DECLSPEC int opal_pointer_array_set_item(opal_pointer_array_t *array, int index, void *value)
Set the value of an element in array.
Definition: opal_pointer_array.c:164
Definition: evdns.c:158

Finalize a request.

This is a macro to avoid function call overhead, since this is typically invoked in the critical performance path (since requests may be re-used, it is possible that we will have to finalize a request multiple times).

When finalizing a request, if MPI_Request_f2c() was previously invoked on that request, then this request was added to the f2c table, and we need to remove it

This function should be called only from the MPI layer. It should never be called from the PML. It take care of the upper level clean-up. When the user call MPI_Request_free we should release all MPI level ressources, so we have to call this function too.

Referenced by ompi_request_finalize(), and ompi_request_persistent_proc_null_free().

#define OMPI_REQUEST_INIT (   request,
  persistent 
)
Value:
do { \
(request)->req_complete = false; \
(request)->req_state = OMPI_REQUEST_INACTIVE; \
(request)->req_persistent = (persistent); \
} while (0);
Definition: evdns.c:158

Initialize a request.

This is a macro to avoid function call overhead, since this is typically invoked in the critical performance path (since requests may be re-used, it is possible that we will have to initialize a request multiple times).

#define PREDEFINED_REQUEST_PAD   (sizeof(void*) * 32)

Padded struct to maintain back compatibiltiy.

See ompi/communicator/communicator.h comments with struct ompi_communicator_t for full explanation why we chose the following padding construct for predefines.

Typedef Documentation

typedef int(* ompi_request_test_all_fn_t)(size_t count, ompi_request_t **requests, int *completed, ompi_status_public_t *statuses)

Non-blocking test for request completion.

Parameters
count(IN) Number of requests
requests(IN) Array of requests
completed(OUT) Flag indicating wether all requests completed.
statuses(OUT) Array of completion statuses.
Returns
OMPI_SUCCESS or failure status.

This routine returns completed==true if all requests completed without errors have completed. The statuses parameter is only updated if all requests completed. Likewise, the requests array is not modified (no requests freed), unless all requests have completed.

typedef int(* ompi_request_test_any_fn_t)(size_t count, ompi_request_t **requests, int *index, int *completed, ompi_status_public_t *status)

Non-blocking test for request completion.

Parameters
count(IN) Number of requests
request(IN) Array of requests
index(OUT) Index of first completed request.
complete(OUT) Flag indicating if index is valid (a request completed).
status(OUT) Status of completed request.
Returns
OMPI_SUCCESS or failure status.

Note that upon completion, the request completed without error is freed, and the request handle at index set to NULL.

typedef int(* ompi_request_test_fn_t)(ompi_request_t **rptr, int *completed, ompi_status_public_t *status)

Non-blocking test for request completion.

Parameters
request(IN) Array of requests
complete(OUT) Flag indicating if index is valid (a request completed).
status(OUT) Status of completed request.
Returns
OMPI_SUCCESS or failure status.

Note that upon completion, the request completed without error is freed, and the request handle at index set to NULL.

typedef int(* ompi_request_test_some_fn_t)(size_t count, ompi_request_t **requests, int *outcount, int *indices, ompi_status_public_t *statuses)

Non-blocking test for some of N requests to complete.

Parameters
count(IN) Number of requests
requests(INOUT) Array of requests
outcount(OUT) Number of finished requests
indices(OUT) Indices of the finished requests
statuses(OUT) Array of completion statuses.
Returns
OMPI_SUCCESS, OMPI_ERR_IN_STATUS or failure status.
typedef int(* ompi_request_wait_all_fn_t)(size_t count, ompi_request_t **requests, ompi_status_public_t *statuses)

Wait (blocking-mode) for all of N requests to complete.

This function is slightly different from the MPI counter-part as it does not release the requests completed with error. Instead, the caller is responsible to call the ompi_request_free.

Parameters
count(IN) Number of requests
requests(IN) Array of requests
statuses(OUT) Array of completion statuses.
Returns
OMPI_SUCCESS or failure status.
typedef int(* ompi_request_wait_any_fn_t)(size_t count, ompi_request_t **requests, int *index, ompi_status_public_t *status)

Wait (blocking-mode) for one of N requests to complete.

This function is slightly different from the MPI counter-part as it does not release the requests completed with error. Instead, the caller is responsible to call the ompi_request_free.

Parameters
count(IN) Number of requests
requests(IN) Array of requests
index(OUT) Index into request array of completed request.
status(OUT) Status of completed request.
Returns
OMPI_SUCCESS or failure status.
typedef int(* ompi_request_wait_fn_t)(ompi_request_t **req_ptr, ompi_status_public_t *status)

Wait (blocking-mode) for one requests to complete.

This function is slightly different from the MPI counter-part as it does not release the requests completed with error. Instead, the caller is responsible to call the ompi_request_free.

Parameters
request(IN) Pointer to request.
status(OUT) Status of completed request.
Returns
OMPI_SUCCESS or failure status.
typedef int(* ompi_request_wait_some_fn_t)(size_t count, ompi_request_t **requests, int *outcount, int *indices, ompi_status_public_t *statuses)

Wait (blocking-mode) for some of N requests to complete.

This function is slightly different from the MPI counter-part as it does not release the requests completed with error. Instead, the caller is responsible to call the ompi_request_free.

Parameters
count(IN) Number of requests
requests(INOUT) Array of requests
outcount(OUT) Number of finished requests
indices(OUT) Indices of the finished requests
statuses(OUT) Array of completion statuses.
Returns
OMPI_SUCCESS, OMPI_ERR_IN_STATUS or failure status.

Function Documentation

static int ompi_request_complete ( ompi_request_t request,
bool  with_signal 
)
inlinestatic

Signal or mark a request as complete.

If with_signal is true this will wake any thread pending on the request and ompi_request_lock should be held while calling this function. If with_signal is false, there will signal generated, and no lock required. This is a special case when the function is called from the critical path for small messages, where we know the current execution flow created the request, and is still in the _START macro.

References ompi_request_t::req_complete, ompi_request_t::req_complete_cb, and ompi_request_t::req_status.

static int ompi_request_free ( ompi_request_t **  request)
inlinestatic

Free a request.

Parameters
request(INOUT) Pointer to request.

Referenced by ompi_errhandler_request_invoke().