TABLE OF CONTENTS

1. Component Library/Passive Lock
2. Component Library: Passive Lock/cl_plock_acquire
3. Component Library: Passive Lock/cl_plock_construct
4. Component Library: Passive Lock/cl_plock_destroy
5. Component Library: Passive Lock/cl_plock_excl_acquire
6. Component Library: Passive Lock/cl_plock_init
7. Component Library: Passive Lock/cl_plock_release
8. Component Library: Passive Lock/cl_plock_t

Component Library/Passive Lock

    Passive Lock

    The Passive Lock provides synchronization between multiple threads that
    are sharing the lock with a single thread holding the lock exclusively.

    Passive lock works exclusively between threads and cannot be used in
    situations where the caller cannot be put into a waiting state.

    The passive lock functions operate a cl_plock_t structure which should
    be treated as opaque and should be manipulated only through the provided 
    functions.

    Structures:
        cl_plock_t

    Initialization:
        cl_plock_construct, cl_plock_init, cl_plock_destroy

    Manipulation
        cl_plock_acquire, cl_plock_excl_acquire, cl_plock_release

Component Library: Passive Lock/cl_plock_acquire

    cl_plock_acquire

    The cl_plock_acquire function acquires a passive lock for
    shared access.

 void
cl_plock_acquire(
    IN  cl_plock_t* const   p_lock ;

    p_lock
        [in] Pointer to a cl_plock_t structure to acquire.

    This function does not return a value.

    Passive Lock, cl_plock_release, cl_plock_excl_acquire

Component Library: Passive Lock/cl_plock_construct

    cl_plock_construct

    The cl_plock_construct function initializes the state of a
    passive lock.

 void
cl_plock_construct(
    IN  cl_plock_t* const   p_lock ;

    p_lock
        [in] Pointer to a cl_plock_t structure whose state to initialize.

    This function does not return a value.

    Allows calling cl_plock_destroy without first calling cl_plock_init.

    Calling cl_plock_construct is a prerequisite to calling any other
    passive lock function except cl_plock_init.

    Passive Lock, cl_plock_init, cl_plock_destroy

Component Library: Passive Lock/cl_plock_destroy

    cl_plock_destroy

    The cl_plock_destroy function performs any necessary cleanup
    of a passive lock.

 void
cl_plock_destroy(
    IN  cl_plock_t* const   p_lock ;

    p_lock
        [in] Pointer to a cl_plock_t structure whose state to initialize.

    This function does not return a value.

    cl_plock_destroy performs any necessary cleanup of the specified
    passive lock.

    This function must only be called if cl_plock_construct or
    cl_plock_init has been called. The passive lock must not be held
    when calling this function.

    Passive Lock, cl_plock_construct, cl_plock_init

Component Library: Passive Lock/cl_plock_excl_acquire

    cl_plock_excl_acquire

    The cl_plock_excl_acquire function acquires exclusive access
    to a passive lock.

 void
cl_plock_excl_acquire(
    IN  cl_plock_t* const   p_lock ;

    p_lock
        [in] Pointer to a cl_plock_t structure to acquire exclusively.

    This function does not return a value.

    Passive Lock, cl_plock_release, cl_plock_acquire

Component Library: Passive Lock/cl_plock_init

    cl_plock_init

    The cl_plock_init function initializes a passive lock.

 cl_status_t
cl_plock_init(
    IN  cl_plock_t* const   p_lock ;

    p_lock
        [in] Pointer to a cl_plock_t structure to initialize.

    CL_SUCCESS if the passive lock was initialized successfully.

    CL_ERROR otherwise.

    Allows calling cl_plock_acquire, cl_plock_release,
    cl_plock_excl_acquire, and cl_plock_excl_release.

    Passive Lock, cl_plock_construct, cl_plock_destroy,
    cl_plock_excl_acquire, cl_plock_excl_release,
    cl_plock_acquire, cl_plock_release

Component Library: Passive Lock/cl_plock_release

    cl_plock_release

    The cl_plock_release function releases a passive lock from
    shared or exclusive access.

 void
cl_plock_release(
    IN  cl_plock_t* const   p_lock ;

    p_lock
        [in] Pointer to a cl_plock_t structure to release.

    This function does not return a value.

    Passive Lock, cl_plock_acquire, cl_plock_excl_acquire

Component Library: Passive Lock/cl_plock_t

    cl_plock_t

    Passive Lock structure.

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

typedef struct _cl_plock
{
    cl_event_t      reader_event;
    cl_event_t      writer_event;
    atomic32_t      reader_count;

} cl_plock_t;

    reader_event
        Event used to synchronize shared access to the lock.

    writer_event
        Event used to synchronize exclusive access to the lock.

    reader_count
        Number of threads holding the lock for shared access.

    Passive Lock