bstr_asynchronous_request_wait(3) — Subroutines

Name

bstr_asynchronous_request_wait − Waits for termination of, and completes, one or more service requests issued in non-blocking mode.

Syntax

bstr_t_status bstr_asynchronous_request_wait (
                                  bstr_t_descriptor   ∗request_set,
                                  bstr_t_wait_mode    mode,
                                  bstr_t_integer32    timeout,
                                  bstr_t_private      error_stack,
                                  bstr_t_rcb          ∗control );

Description

The bstr_asynchronous_request_wait procedure checks to see whether the pending non-blocking requests specified in request_set have completed. For those that have completed, it activates the callback routine (if any). Depending on the value of mode, the bstr_asynchronous_request_wait procedure waits for termination of at least one of the pending requests (or all of them).

The timeout argument determines the time interval (in seconds) that the bstr_asynchronous_request_wait procedure waits for termination of the specified pending procedures. The value BSTR_C_WAIT_FOREVER indicates an unlimited time.

If timeout is set to BSTR_C_NO_WAIT, the bstr_asynchronous_request_wait procedure tests to see whether at least one of the procedures are terminated, or all of them (depending on the value of mode). If there are terminated procedures, they will be completed as explained above. In any case, control will be returned immediately to the calling application.

This procedure cannot be invoked from within a callback routine.

Arguments

request_set
access: read
The address of a bstr_t_descriptor data structure, which specifies the number of elements (maximum BSTR_C_MAX_REQUESTS) and the address of an array.

Each array element contains the address of a request control block, as previously specified in a service request issued in non-blocking mode. An element in the array can be set to NULL, in which case BASEstar Open will ignore it.

If request_set is set to NULL, the bstr_asynchronous_request_wait procedure considers all the pending service requests.

mode
access: read
Determines the possible execution modes of the bstr_asynchronous_request_wait procedure. The table below lists the valid input for this argument:

Constant Name	Description
BSTR_C_ANY_REQUEST	The bstr_asynchronous_request_wait procedure waits for termination of at least one of the pending non-blocking service requests specified in request_set. When a pending service request is terminated, the associated callback routine is executed and then control is returned to the calling application.
BSTR_C_ALL_REQUESTS	The bstr_asynchronous_request_wait procedure waits for termination of all pending non-blocking service requests specified in request_set, before returning control to the calling application.

timeout
access: read
Determines the time interval (in seconds) that the bstr_asynchronous_request_wait procedure waits for termination of one or more service requests, according to the value of mode. The behavior of the bstr_asynchronous_request_wait procedure varies according to the value of timeout, as follows:

•Any positive value is taken as a finite time interval that the procedure must wait. In this case, the procedure terminates when the condition specified by mode is met within the specified time interval.

If mode is set to BSTR_C_ALL_REQUESTS, BASEstar Open returns control to the application when all pending requests have been completed, or when timeout has expired before completion of all pending requests.

•The value BSTR_C_WAIT_FOREVER means that there is no time limit, and the procedure completes when the condition specified by mode is met.

•The value BSTR_C_NO_WAIT means that the outcome depends on the value of the mode parameter, as follows:

•If mode is set to BSTR_C_ANY_REQUEST, the bstr_asynchronous_request_wait procedure tests whether any procedures indicated in the request_set argument have terminated. If so, the associated callback routine of the terminated procedure is executed, and then control is returned to the calling application. If not, control is returned immediately to the calling application with no action.

•If mode is set to BSTR_C_ALL_REQUESTS, the bstr_asynchronous_request_wait procedure tests whether all the procedures indicated in the request_set argument have terminated. If so, the associated callback routines are executed, and then control is returned to the calling application. If not, control is returned immediately to the calling application with no action.

error_stack
access: read
The address of an optional error stack. If specified, the error stack returns any errors related to the operation of the bstr_asynchronous_request_wait procedure.

control
access: write
This argument is only significant if mode is set to BSTR_C_ANY_REQUEST. In this case, the request control block associated with the service request just completed is copied into control.

Return Values