ACE_Condition(3)

NAME

ACE_Condition - ACE_Condition variable wrapper, which allows threads to block until shared data changes state.

SYNOPSIS

#include <ace/Synch_T.h>
template<class MUTEX>
class ACE_Condition
{
  public:
    ACE_Condition (
        MUTEX &m,
        int type = USYNC_THREAD,
        LPCTSTR name = 0,
        void *arg = 0
        );
    ~ACE_Condition (void);
    int wait (const ACE_Time_Value *abstime);
    int wait (void);
    int wait (MUTEX &mutex, const ACE_Time_Value *abstime = 0);
    int signal (void);
    int broadcast (void);
    int remove (void);
    MUTEX &mutex (void);
    void dump (void) const;
  protected:
    ACE_cond_t *process_cond_;
    LPCTSTR condname_;
    ACE_cond_t cond_;
    MUTEX &mutex_;
  private:
    inline ACE_UNIMPLEMENTED_FUNC (
        void operator= (const ACE_Condition<MUTEX> &)
        );
};

DESCRIPTION

A condition variable enables threads to atomically block and test the condition under the protection of a mutual exclu- sion lock (mutex) until the condition is satisfied. That is, the mutex must have been held by the thread before calling wait or signal on the condition. If the condition is false, a thread blocks on a condition variable and atomically releases the mutex that is waiting for the condition to change. If another thread changes the condition, it may wake up waiting threads by signaling the associated condition variable. The waiting threads, upon awakening, reacquire the mutex and re-evaluate the condition.

Note, you can only parameterize ACE_Condition with ACE_Thread_Mutex or ACE_Null_Mutex.

Initialiation and termination methods.

ACE_Condition (
    MUTEX &m,
    int type = USYNC_THREAD,
    LPCTSTR name = 0,
    void *arg = 0
    );

Initialize the condition variable.

~ACE_Condition (void);

Implicitly destroy the condition variable.

Lock accessors.

int wait (const ACE_Time_Value *abstime);

Block on condition, or until absolute time-of-day has passed. If abstime == 0 use "blocking" wait semantics. Else, if abstime != 0 and the call times out before the condition is signaled wait returns -1 and sets errno to ETIME.

int wait (void);

Block on condition.

int wait (MUTEX &mutex, const ACE_Time_Value *abstime = 0);

Block on condition or until absolute time-of-day has passed. If abstime == 0 use "blocking" wait() semantics on the mutex passed as a parameter (this is useful if you need to store the Condition in shared memory). Else, if abstime != 0 and the call times out before the condition is signaled wait returns -1 and sets errno to ETIME.

int signal (void);

Signal one waiting thread.

int broadcast (void);

Signal *all* waiting threads.

Utility methods.

int remove (void);

Explicitly destroy the condition variable.

MUTEX &mutex (void);

Returns a reference to the underlying mutex_;

void dump (void) const;

Dump the state of an object.

ACE_ALLOC_HOOK_DECLARE; Declare the dynamic allocation hooks.

Prevent assignment and initialization.

inline ACE_UNIMPLEMENTED_FUNC (
    void operator= (const ACE_Condition<MUTEX> &)
    );

AUTHOR

Doug Schmidt

LIBRARY

ace