Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

ACE_Semaphore Class Reference

Wrapper for Dijkstra style general semaphores. More...

#include <Synch.h>

Inheritance diagram for ACE_Semaphore:

Inheritance graph
[legend]
List of all members.

Public Methods

 ACE_Semaphore (u_int count=1, int type=USYNC_THREAD, const ACE_TCHAR *name=0, void *=0, int max=0x7fffffff)
 Initialize the semaphore, with initial value of "count". More...

 ~ACE_Semaphore (void)
 Implicitly destroy the semaphore. More...

int remove (void)
int acquire (void)
 Block the thread until the semaphore count becomes greater than 0, then decrement it. More...

int acquire (ACE_Time_Value &tv)
int acquire (ACE_Time_Value *tv)
int tryacquire (void)
int release (void)
 Increment the semaphore by 1, potentially unblocking a waiting thread. More...

int release (u_int release_count)
 Increment the semaphore by <release_count>, potentially unblocking waiting threads. More...

int acquire_read (void)
int acquire_write (void)
int tryacquire_read (void)
int tryacquire_write (void)
int tryacquire_write_upgrade (void)
void dump (void) const
 Dump the state of an object. More...

const ACE_sema_t & lock (void) const
 Return the underlying lock. More...


Public Attributes

 ACE_ALLOC_HOOK_DECLARE
 Declare the dynamic allocation hooks. More...


Protected Attributes

ACE_sema_t semaphore_
int removed_
 Keeps track of whether <remove> has been called yet to avoid multiple <remove> calls, e.g., explicitly and implicitly in the destructor. This flag isn't protected by a lock, so make sure that you don't have multiple threads simultaneously calling <remove> on the same object, which is a bad idea anyway... More...


Private Methods

void operator= (const ACE_Semaphore &)
 ACE_Semaphore (const ACE_Semaphore &)

Detailed Description

Wrapper for Dijkstra style general semaphores.

Definition at line 160 of file Synch.h.

Constructor & Destructor Documentation

ACE_Semaphore::ACE_Semaphore (  u_int    count = 1,
int    type = USYNC_THREAD,
const ACE_TCHAR *    name = 0,
void *    = 0,
int    max = 0x7fffffff
) 
 

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

Definition at line 141 of file Synch.cpp.

References ACE_ERROR, ACE_LIB_TEXT, ACE_TCHAR, ACE_UNIQUE_NAME_LEN, LM_ERROR, ACE_OS::sema_init, and ACE::unique_name. 

00146   : removed_ (0)
00147 {
00148 // ACE_TRACE ("ACE_Semaphore::ACE_Semaphore");
00149 #if defined(ACE_LACKS_UNNAMED_SEMAPHORE)
00150 // if the user does not provide a name, we generate a unique name here
00151   ACE_TCHAR iname[ACE_UNIQUE_NAME_LEN];
00152   if (name == 0) 
00153     ACE::unique_name (this, iname, ACE_UNIQUE_NAME_LEN);
00154   if (ACE_OS::sema_init (&this->semaphore_, count, type,
00155                          name ? name : iname, 
00156                          arg, max) != 0)
00157 #else
00158   if (ACE_OS::sema_init (&this->semaphore_, count, type,
00159                          name, arg, max) != 0)
00160 #endif
00161     ACE_ERROR ((LM_ERROR,
00162                 ACE_LIB_TEXT ("%p\n"),
00163                 ACE_LIB_TEXT ("ACE_Semaphore::ACE_Semaphore")));
00164 }

ACE_Semaphore::~ACE_Semaphore (  void    ) 
 

Implicitly destroy the semaphore.

Definition at line 166 of file Synch.cpp.

References remove. 

00167 {
00168 // ACE_TRACE ("ACE_Semaphore::~ACE_Semaphore");
00169 
00170   this->remove ();
00171 }

ACE_Semaphore::ACE_Semaphore (  const ACE_Semaphore &    )  [private]
 

Member Function Documentation

ACE_INLINE int ACE_Semaphore::acquire (  ACE_Time_Value *    tv ) 
 

If <tv> == 0 then call <acquire()> directly. Otherwise, Block the thread until the semaphore count becomes greater than 0 (at which point it is decremented) or until <tv> times out (in which case -1 is returned and <errno> == <ETIME>). Note that <*tv> is assumed to be in "absolute" rather than "relative" time. The value of <*tv> is updated upon return to show the actual (absolute) acquisition time.

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 -DACE_HAS_PTHREADS, rather than -DACE_HAS_STHREADS or -DACE_HAS_POSIX_SEM.

Definition at line 285 of file Synch.i.

References ACE_OS::sema_wait. 

00286 {
00287 // ACE_TRACE ("ACE_Semaphore::acquire");
00288   return ACE_OS::sema_wait (&this->semaphore_, tv);
00289 }

ACE_INLINE int ACE_Semaphore::acquire (  ACE_Time_Value &    tv ) 
 

Block the thread until the semaphore count becomes greater than 0 (at which point it is decremented) or until <tv> times out (in which case -1 is returned and <errno> == <ETIME>). Note that <tv> is assumed to be in "absolute" rather than "relative" time. The value of <tv> is updated upon return to show the actual (absolute) acquisition time.

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 -DACE_HAS_PTHREADS, rather than -DACE_HAS_STHREADS or -DACE_HAS_POSIX_SEM.

Definition at line 278 of file Synch.i.

References ACE_OS::sema_wait. 

00279 {
00280 // ACE_TRACE ("ACE_Semaphore::acquire");
00281   return ACE_OS::sema_wait (&this->semaphore_, tv);
00282 }

ACE_INLINE int ACE_Semaphore::acquire (  void    ) 
 

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

Definition at line 271 of file Synch.i.

References ACE_OS::sema_wait.

Referenced by ACE_Process_Semaphore::acquire, acquire_read, acquire_write, and ACE_Token::ACE_Token_Queue_Entry::wait. 

00272 {
00273 // ACE_TRACE ("ACE_Semaphore::acquire");
00274   return ACE_OS::sema_wait (&this->semaphore_);
00275 }

ACE_INLINE int ACE_Semaphore::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.

Definition at line 317 of file Synch.i.

References acquire. 

00318 {
00319   return this->acquire ();
00320 }

ACE_INLINE int ACE_Semaphore::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.

Definition at line 327 of file Synch.i.

References acquire. 

00328 {
00329   return this->acquire ();
00330 }

void ACE_Semaphore::dump (  void    )  const
 

Dump the state of an object.

Reimplemented in ACE_Thread_Semaphore.

Definition at line 132 of file Synch.cpp.

References ACE_BEGIN_DUMP, ACE_DEBUG, ACE_END_DUMP, ACE_LIB_TEXT, and LM_DEBUG.

Referenced by ACE_Thread_Semaphore::dump, and ACE_Process_Semaphore::dump. 

00133 {
00134 // ACE_TRACE ("ACE_Semaphore::dump");
00135 
00136   ACE_DEBUG ((LM_DEBUG, ACE_BEGIN_DUMP, this));
00137   ACE_DEBUG ((LM_DEBUG, ACE_LIB_TEXT ("\n")));
00138   ACE_DEBUG ((LM_DEBUG, ACE_END_DUMP));
00139 }

ACE_INLINE const ACE_sema_t & ACE_Semaphore::lock (  void    )  const
 

Return the underlying lock.

Definition at line 251 of file Synch.i.

References semaphore_. 

00252 {
00253 // ACE_TRACE ("ACE_Semaphore::lock");
00254   return this->semaphore_;
00255 }

void ACE_Semaphore::operator= (  const ACE_Semaphore &    )  [private]
 

ACE_INLINE int ACE_Semaphore::release (  u_int    release_count ) 
 

Increment the semaphore by <release_count>, potentially unblocking waiting threads.

Definition at line 306 of file Synch.i.

References ACE_OS::sema_post. 

00307 {
00308 // ACE_TRACE ("ACE_Semaphore::release");
00309   return ACE_OS::sema_post (&this->semaphore_, release_count);
00310 }

ACE_INLINE int ACE_Semaphore::release (  void    ) 
 

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

Definition at line 299 of file Synch.i.

References ACE_OS::sema_post.

Referenced by ACE_Process_Semaphore::release, and ACE_Token::ACE_Token_Queue_Entry::signal. 

00300 {
00301 // ACE_TRACE ("ACE_Semaphore::release");
00302   return ACE_OS::sema_post (&this->semaphore_);
00303 }

ACE_INLINE int ACE_Semaphore::remove (  void    ) 
 

Explicitly destroy the semaphore. Note that only one thread should call this method since it doesn't protect against race conditions.

Definition at line 258 of file Synch.i.

References removed_, and ACE_OS::sema_destroy.

Referenced by ACE_Process_Semaphore::remove, and ~ACE_Semaphore. 

00259 {
00260 // ACE_TRACE ("ACE_Semaphore::remove");
00261   int result = 0;
00262   if (this->removed_ == 0)
00263     {
00264       this->removed_ = 1;
00265       result = ACE_OS::sema_destroy (&this->semaphore_);
00266     }
00267   return result;
00268 }

ACE_INLINE int ACE_Semaphore::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>.

Definition at line 292 of file Synch.i.

References ACE_OS::sema_trywait.

Referenced by ACE_Process_Semaphore::tryacquire, tryacquire_read, and tryacquire_write. 

00293 {
00294 // ACE_TRACE ("ACE_Semaphore::tryacquire");
00295   return ACE_OS::sema_trywait (&this->semaphore_);
00296 }

ACE_INLINE int ACE_Semaphore::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>.

Definition at line 337 of file Synch.i.

References tryacquire. 

00338 {
00339   return this->tryacquire ();
00340 }

ACE_INLINE int ACE_Semaphore::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>.

Definition at line 347 of file Synch.i.

References tryacquire. 

00348 {
00349   return this->tryacquire ();
00350 }

ACE_INLINE int ACE_Semaphore::tryacquire_write_upgrade (  void    ) 
 

This is only here to make the <ACE_Semaphore> interface consistent with the other synchronization APIs. Assumes the caller has already acquired the semaphore using one of the above calls, and returns 0 (success) always.

Definition at line 357 of file Synch.i. 

00358 {
00359   return 0;
00360 }

Member Data Documentation

ACE_Semaphore::ACE_ALLOC_HOOK_DECLARE
 

Declare the dynamic allocation hooks.

Reimplemented in ACE_Thread_Semaphore.

Definition at line 278 of file Synch.h.

int ACE_Semaphore::removed_ [protected]
 

Keeps track of whether <remove> has been called yet to avoid multiple <remove> calls, e.g., explicitly and implicitly in the destructor. This flag isn't protected by a lock, so make sure that you don't have multiple threads simultaneously calling <remove> on the same object, which is a bad idea anyway...

Definition at line 291 of file Synch.h.

Referenced by remove.

ACE_sema_t ACE_Semaphore::semaphore_ [protected]
 

Definition at line 284 of file Synch.h.

Referenced by lock.

The documentation for this class was generated from the following files:
Generated on Mon Jun 16 12:55:48 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002