## NAME

ACE_Semaphore - Wrapper for Dijkstra style general semaphores.

## SYNOPSIS

    #include <ace/Synch.h>

    class ACE_Semaphore
    {
      public:
        ACE_Semaphore (
            u_int count = 1,
            int type = USYNC_THREAD,
            LPCTSTR name = 0,
            void * = 0,
            int max = 0x7fffffff
            );
        ~ACE_Semaphore (void);
        int remove (void);
        int acquire (void);
        int acquire (ACE_Time_Value &tv);
        int tryacquire (void);
        int release (void);
        int release (size_t release_count);
        int acquire_read (void);
        int acquire_write (void);
        int tryacquire_read (void);
        int tryacquire_write (void);
        void dump (void) const;
        ACE_ALLOC_HOOK_DECLARE;
        const ACE_sema_t &lock (void) const;
      protected:
        ACE_sema_t semaphore_;
        int removed_;
      private:
        void operator= (const ACE_Semaphore &);
        ACE_Semaphore (const ACE_Semaphore &);
    };

## DESCRIPTION

Wrappers for various synchronization routines.

## Initialization and termination.

    ACE_Semaphore (
        u_int count = 1,
        int type = USYNC_THREAD,
        LPCTSTR name = 0,
        void * = 0,
        int max = 0x7fffffff
        );

Initialize the semaphore, with initial value of "count".

    ~ACE_Semaphore (void);

Implicitly destroy the semaphore.

    int remove (void);

Explicitly destroy the semaphore.

    int acquire (void);

Block the thread until the semaphore count becomes greater than 0, then decrement it.

    int acquire (ACE_Time_Value &tv);

Block the thread until `tv` times out or until the semaphore count becomes greater than 0 (at which point it is decremented). Note that `tv` is assumed to be in "absolute" rather than "relative" time. The value of `tv` is updated upon return, i.e., the caller gets the amount of time that has elapsed while waiting to acquire the semaphore.

NOTE: Solaris threads do not support timed semaphores. Therefore, if you're running on Solaris you might want to consider using the ACE POSIX pthreads implementation instead, which can be enabled by compiling ACE with -D_POSIX_PTHREAD_SEMANTICS.

    int tryacquire (void);

Conditionally decrement the semaphore if count is greater than 0 (i.e., won't block). Returns -1 on failure. If we "failed" because someone else already had the lock, `errno` is set to `EBUSY`.

    int release (void);

Increment the semaphore by 1, potentially unblocking a waiting thread.

    int release (size_t release_count);

Increment the semaphore by `release_count`, potentially unblocking waiting threads.

    int acquire_read (void);

Acquire semaphore ownership. This calls `acquire` and is only here to make the `ACE_Semaphore` interface consistent with the other synchronization APIs.

    int acquire_write (void);

Acquire semaphore ownership. This calls `acquire` and is only here to make the `ACE_Semaphore` interface consistent with the other synchronization APIs.

    int tryacquire_read (void);

Conditionally acquire semaphore (i.e., won't block). This calls `tryacquire` and is only here to make the `ACE_Semaphore` interface consistent with the other synchronization APIs. Returns -1 on failure. If we "failed" because someone else already had the lock, `errno` is set to `EBUSY`.

    int tryacquire_write (void);

Conditionally acquire semaphore (i.e., won't block). This calls `tryacquire` and is only here to make the `ACE_Semaphore` interface consistent with the other synchronization APIs. Returns -1 on failure. If we "failed" because someone else already had the lock, `errno` is set to `EBUSY`.

    void dump (void) const;

Dump the state of an object.

    ACE_ALLOC_HOOK_DECLARE;

Declare the dynamic allocation hooks.

    const ACE_sema_t &lock (void) const;

Return the underlying lock.

## Prevent assignment and initialization.

    void operator= (const ACE_Semaphore &);

    ACE_Semaphore (const ACE_Semaphore &);

## AUTHOR

Doug Schmidt

## LIBRARY

ace