TABLE OF CONTENTS

1. Component Library/Request Manager
2. Component Library: Request Manager/cl_pfn_req_cb_t
3. Component Library: Request Manager/cl_pfn_reqmgr_get_count_t
4. Component Library: Request Manager/cl_req_mgr_construct
5. Component Library: Request Manager/cl_req_mgr_destroy
6. Component Library: Request Manager/cl_req_mgr_get
7. Component Library: Request Manager/cl_req_mgr_init
8. Component Library: Request Manager/cl_req_mgr_resume
9. Component Library: Request Manager/cl_req_mgr_t
10. Component Library: Request Manager/cl_req_type_t

Component Library/Request Manager

    Request Manager

    The Request Manager manages synchronous as well as asynchronous
    requests for objects.

    Request manager does not supply the objects, but merely returns whether
    objects are available to satisfy requests. This allows users to use
    various sources for objects.

    While the request manager manages synchronous and asynchronous requests
    for objects, it does not itself operate asynchronously. Instead, the
    cl_req_mgr_resume function returns information for resuming asynchronous
    requests. If a call to cl_req_mgr_resume returns CL_SUCCESS, additional
    requests may be able to resume. It is recommended that users flush
    pending requests by calling cl_req_mgr_resume while CL_SUCCESS is returned.

    The request manager functions operates on a cl_req_mgr_t structure which 
    should be treated as opaque and should be manipulated only through the 
    provided functions.

    Types:
        cl_req_type_t

    Structures:
        cl_req_mgr_t

    Callbacks:
        cl_pfn_req_cb_t, cl_pfn_reqmgr_get_count_t
    
    Initialization/Destruction:
        cl_req_mgr_construct, cl_req_mgr_init, cl_req_mgr_destroy

    Manipulation:
        cl_req_mgr_get, cl_req_mgr_resume

    Attributes:
        cl_is_req_mgr_inited, cl_req_mgr_count 

Component Library: Request Manager/cl_pfn_req_cb_t

    cl_pfn_req_cb_t

    The cl_pfn_req_cb_t function type defines the prototype for functions
    used to store a function pointer to a user defined function.

typedef void
(*cl_pfn_req_cb_t)( void );

    This function does not take parameters.

    This function does not return a value.

    Function pointers specified by this parameter do not have to match the
    defined syntax, as these callbacks are never invoked directly by the
    request manager.  When specifying a function with a different prototype,
    cast the function pointer to this type.

    Request Manager, cl_req_mgr_get, cl_req_mgr_resume

Component Library: Request Manager/cl_pfn_reqmgr_get_count_t

    cl_pfn_reqmgr_get_count_t

    The cl_pfn_reqmgr_get_count_t function type defines the prototype for
    functions used to retrieve the number of available objects in a pool.

typedef size_t
(*cl_pfn_reqmgr_get_count_t)(
    IN  void*   context );

    Context
        [in] Context provided in a call to cl_req_mgr_init by
        the get_context parameter.

    Returns the number of objects available in an object pool for which
    requests are managed by a request manager.

    This function type is provided as function prototype reference for the
    function passed into cl_req_mgr_init. This function is invoked by the
    request manager when trying to fulfill requests for resources, either
    through a call to cl_req_mgr_get or cl_req_mgr_resume.

    Request Manager, cl_req_mgr_init, cl_req_mgr_get, cl_req_mgr_resume

Component Library: Request Manager/cl_req_mgr_construct

    cl_req_mgr_construct

    The cl_req_mgr_construct function constructs a request manager.

void
cl_req_mgr_construct(
    IN  cl_req_mgr_t* const p_req_mgr );

    p_req_mgr
        [in] Pointer to a cl_req_mgr_t structure to construct.

    This function does not return a value.

    cl_req_mgr_construct allows calling cl_req_mgr_destroy without first
    calling cl_req_mgr_init.

    Calling cl_req_mgr_construct is a prerequisite to calling any other
    request manager function except cl_req_mgr_init.

    Request Manager, cl_req_mgr_init, cl_req_mgr_destroy

Component Library: Request Manager/cl_req_mgr_destroy

    cl_req_mgr_destroy

    The cl_req_mgr_destroy function destroys a request manager.

void
cl_req_mgr_destroy(
    IN  cl_req_mgr_t* const p_req_mgr );

    p_req_mgr
        [in] Pointer to a cl_req_mgr_t structure to destroy.

    This function does not return a value.

    cl_req_mgr_destroy frees all memory allocated by the request manager.
    Further operations on the request manager should not be attempted.

    This function should only be called after a call to cl_req_mgr_construct
    or cl_req_mgr_init.

    Request Manager, cl_req_mgr_construct, cl_req_mgr_init

Component Library: Request Manager/cl_req_mgr_get

    cl_req_mgr_get

    The cl_req_mgr_get function handles synchronous and asynchronous
    requests for objects.

cl_status_t
cl_req_mgr_get(
    IN      cl_req_mgr_t* const p_req_mgr,
    IN OUT  size_t* const       p_count,
    IN      const cl_req_type_t req_type,
    IN      cl_pfn_req_cb_t     pfn_callback,
    IN      const void* const   context1,
    IN      const void* const   context2 );

    p_req_mgr
        [in] Pointer to a cl_req_mgr_t structure from which to check
        for resources.

    p_count
        [in/out] On input, contains the number of objects requested.
        On output, contains the number of objects available.

    req_type
        [in] Enumerated type describing the type of request. Valid values are:
            ReqGetSync
                Synchronous request.
            ReqGetAsync
                Asynchronous requests for which all objects are required at
                once.
            ReqGetAsyncPartialOk
                Asynchronous requests that may be broken into multiple smaller
                requests.

    pfn_callback
        [in] Pointer to a callback function for use by the caller. This
        callback function is never invoked by the request manager.

    context1
        [in] First of two contexts for a resource request.

    context2
        [in] Second of two contexts for a resource request.

    CL_SUCCESS if all objects requested are available.

    CL_PENDING if the request could not be completed in its entirety.
    The p_count parameter contains the number of objects immediately available.

    CL_INSUFFICIENT_RESOURCES if the request could not be completed due to
    insufficient objects being available.

    CL_INSUFFICIENT_MEMORY if the request failed due to a lack of system memory.

    Upon successful completion of this function, the p_count parameter contains
    the number of objects available.

    Synchronous requests fail if there are any asynchronous requests pending,
    or if there are not enough resources to immediately satisfy the request in
    its entirety .

    Asynchronous requests fail if there is insufficient system memory to
    queue them.

    Once an asynchronous request is queued, use cl_req_mgr_resume to retrieve
    information for resuming queued requests.

    Request Manager, cl_req_mgr_resume

Component Library: Request Manager/cl_req_mgr_init

    cl_req_mgr_init

    The cl_req_mgr_init function initializes a request manager for use.

cl_status_t
cl_req_mgr_init(
    IN  cl_req_mgr_t* const         p_req_mgr,
    IN  cl_pfn_reqmgr_get_count_t   pfn_get_count,
    IN  const void* const           get_context );

    p_req_mgr
        [in] Pointer to a cl_req_mgr_t structure to initialize.

    pfn_get_count
        [in] Callback function invoked by the request manager to get the
        number of objects available in a pool of objects for which the
        request manager is managing requests.
        See the cl_pfn_req_mgr_get_count_t function type declaration for
        details about the callback function.

    get_context
        [in] Context to pass into the function specified by the
        pfn_get_count parameter.

    CL_SUCCESS if the request manager was successfully initialized.

    CL_INSUFFICIENT_MEMORY if there was not enough memory to initialize
    the request manager.

    Request Manager, cl_req_mgr_construct, cl_req_mgr_destroy, cl_req_mgr_get,
    cl_req_mgr_resume, cl_pfn_req_mgr_get_count_t

Component Library: Request Manager/cl_req_mgr_resume

    cl_req_mgr_resume

    The cl_req_mgr_resume function attempts to resume queued requests.

cl_status_t
cl_req_mgr_resume(
    IN  cl_req_mgr_t* const     p_req_mgr,
    OUT uint32_t* const         p_count,
    OUT cl_pfn_req_cb_t* const  ppfn_callback,
    OUT const void** const      p_context1,
    OUT const void** const      p_context2 );

    p_req_mgr
        [in] Pointer to a cl_req_mgr_t structure from which to resume requests.

    p_count
        [out] Contains the number of objects available for a resuming request.

    ppfn_callback
        [out] Contains the pfn_callback value for the resuming request, as
        provided to the call to the cl_req_mgr_get function.

    p_context1
        [out] Contains the context1 value for the resuming request, as provided
        to the call to the cl_req_mgr_get function.

    p_context2
        [out] Contains the context2 value for the resuming request, as provided
        to the call to the cl_req_mgr_get function.

    CL_SUCCESS if a request was completed.

    CL_PENDING if a request was continued, but not completed.

    CL_INSUFFICIENT_RESOURCES if a request could not be continued due to
    a lack of resources.

    CL_NOT_DONE if there were no pending requests.

    cl_req_mgr_resume resumes at most one request. Further requests may be
    able to be resumed if this call returns CL_SUCCESS.

    Request Manager, cl_req_mgr_get

Component Library: Request Manager/cl_req_mgr_t

    cl_req_mgr_t

    Quick composite pool structure.

    The cl_req_mgr_t structure should be treated as opaque and should be
    manipulated only through the provided functions.

typedef struct _cl_req_mgr
{
    cl_pfn_reqmgr_get_count_t   pfn_get_count;
    const void                  *get_context;
    cl_qlist_t                  request_queue;
    cl_qpool_t                  request_pool;

} cl_req_mgr_t;

    pfn_get_count
        Pointer to the count callback function.

    get_context
        Context to pass as single parameter to count callback.

    request_queue
        Pending requests for elements.

    request_pool
        Pool of request structures for storing requests in the request queue.

    Request Manager

Component Library: Request Manager/cl_req_type_t

    cl_req_type_t

    The cl_req_type_t enumerated type describes the type of request.

typedef enum _cl_req_type
{
    REQ_GET_SYNC,
    REQ_GET_ASYNC,
    REQ_GET_PARTIAL_OK

} cl_req_type_t;

    REQ_GET_SYNC
        Synchronous request.

    REQ_GET_ASYNC
        Asynchronous requests for which all objects are required at once.

    REQ_GET_PARTIAL_OK
        Asynchronous requests that may be broken into multiple smaller requests.

    Request Manager, cl_req_mgr_get