Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

Linux 2.6 - man page for pthread_cond_destroy (linux section 3posix)

PTHREAD_COND_DESTROY(P) 	    POSIX Programmer's Manual		  PTHREAD_COND_DESTROY(P)

NAME
       pthread_cond_destroy, pthread_cond_init - destroy and initialize condition variables

SYNOPSIS
       #include <pthread.h>

       int pthread_cond_destroy(pthread_cond_t *cond);
       int pthread_cond_init(pthread_cond_t *restrict cond,
	      const pthread_condattr_t *restrict attr);
       pthread_cond_t cond = PTHREAD_COND_INITIALIZER;

DESCRIPTION
       The  pthread_cond_destroy()  function shall destroy the given condition variable specified
       by cond; the object  becomes,  in  effect,  uninitialized.  An  implementation  may  cause
       pthread_cond_destroy()  to  set	the  object  referenced  by  cond  to an invalid value. A
       destroyed condition variable object can be reinitialized  using	pthread_cond_init();  the
       results of otherwise referencing the object after it has been destroyed are undefined.

       It  shall  be  safe to destroy an initialized condition variable upon which no threads are
       currently blocked. Attempting to destroy a condition variable upon which other threads are
       currently blocked results in undefined behavior.

       The  pthread_cond_init()  function  shall  initialize the condition variable referenced by
       cond with attributes referenced by attr. If attr is NULL, the default  condition  variable
       attributes  shall be used; the effect is the same as passing the address of a default con-
       dition variable attributes object. Upon successful initialization, the state of the condi-
       tion variable shall become initialized.

       Only  cond  itself may be used for performing synchronization.  The result of referring to
       copies	of   cond   in	 calls	  to	pthread_cond_wait(),	pthread_cond_timedwait(),
       pthread_cond_signal(), pthread_cond_broadcast(), and pthread_cond_destroy() is undefined.

       Attempting  to  initialize  an already initialized condition variable results in undefined
       behavior.

       In  cases  where  default  condition  variable  attributes  are	appropriate,  the   macro
       PTHREAD_COND_INITIALIZER can be used to initialize condition variables that are statically
       allocated. The effect  shall  be  equivalent  to  dynamic  initialization  by  a  call  to
       pthread_cond_init() with parameter attr specified as NULL, except that no error checks are
       performed.

RETURN VALUE
       If successful, the pthread_cond_destroy() and pthread_cond_init() functions  shall  return
       zero; otherwise, an error number shall be returned to indicate the error.

       The [EBUSY] and [EINVAL] error checks, if implemented, shall act as if they were performed
       immediately at the beginning of processing for the function and	caused	an  error  return
       prior to modifying the state of the condition variable specified by cond.

ERRORS
       The pthread_cond_destroy() function may fail if:

       EBUSY  The implementation has detected an attempt to destroy the object referenced by cond
	      while it is referenced (for example, while being used in a  pthread_cond_wait()  or
	      pthread_cond_timedwait()) by another thread.

       EINVAL The value specified by cond is invalid.

       The pthread_cond_init() function shall fail if:

       EAGAIN The system lacked the necessary resources (other than memory) to initialize another
	      condition variable.

       ENOMEM Insufficient memory exists to initialize the condition variable.

       The pthread_cond_init() function may fail if:

       EBUSY  The implementation has detected an attempt to reinitialize the object referenced by
	      cond, a previously initialized, but not yet destroyed, condition variable.

       EINVAL The value specified by attr is invalid.

       These functions shall not return an error code of [EINTR].

       The following sections are informative.

EXAMPLES
       A  condition  variable can be destroyed immediately after all the threads that are blocked
       on it are awakened. For example, consider the following code:

	      struct list {
		  pthread_mutex_t lm;
		  ...
	      }

	      struct elt {
		  key k;
		  int busy;
		  pthread_cond_t notbusy;
		  ...
	      }

	      /* Find a list element and reserve it. */
	      struct elt *
	      list_find(struct list *lp, key k)
	      {
		  struct elt *ep;

		  pthread_mutex_lock(&lp->lm);
		  while ((ep = find_elt(l, k) != NULL) && ep->busy)
		      pthread_cond_wait(&ep->notbusy, &lp->lm);
		  if (ep != NULL)
		      ep->busy = 1;
		  pthread_mutex_unlock(&lp->lm);
		  return(ep);
	      }

	      delete_elt(struct list *lp, struct elt *ep)
	      {
		  pthread_mutex_lock(&lp->lm);
		  assert(ep->busy);
		  ... remove ep from list ...
		  ep->busy = 0;  /* Paranoid. */
	      (A) pthread_cond_broadcast(&ep->notbusy);
		  pthread_mutex_unlock(&lp->lm);
	      (B) pthread_cond_destroy(&rp->notbusy);
		  free(ep);
	      }

       In this example, the condition variable and its list element may be freed (line B) immedi-
       ately after all threads waiting for it are awakened (line A), since the mutex and the code
       ensure that no other thread can touch the element to be deleted.

APPLICATION USAGE
       None.

RATIONALE
       See pthread_mutex_init() ; a similar rationale applies to condition variables.

FUTURE DIRECTIONS
       None.

SEE ALSO
       pthread_cond_broadcast() , pthread_cond_signal() ,  pthread_cond_timedwait()  ,	the  Base
       Definitions volume of IEEE Std 1003.1-2001, <pthread.h>

COPYRIGHT
       Portions  of  this  text  are  reprinted  and  reproduced in electronic form from IEEE Std
       1003.1, 2003 Edition, Standard for Information Technology  --  Portable	Operating  System
       Interface  (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003 by
       the Institute of Electrical and Electronics Engineers, Inc and  The  Open  Group.  In  the
       event  of  any  discrepancy  between this version and the original IEEE and The Open Group
       Standard, the original IEEE and The Open Group Standard is the referee document. The orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003			  PTHREAD_COND_DESTROY(P)


All times are GMT -4. The time now is 08:48 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password