OpenMPI 0.1.1

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

Data Structures | Macros | Typedefs | Functions | Variables
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) { \
opal_pointer_array_set_item(&ompi_request_f_to_c_table, \
(request)->req_f_to_c_index, NULL); \
(request)->req_f_to_c_index = MPI_UNDEFINED; \
} \
} while (0);
ompi_request_f_to_c_table
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_pointer_array_set_item
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
request
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);
request
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
| ) |  |
| inline static

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 | ) |
| inline static

Free a request.

Parameters

  request | (INOUT) Pointer to request.

Referenced by ompi_errhandler_request_invoke().