*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> pthread_once (3)              
Title
Content
Arch
Section
 

pthread_once(3)

Contents


NAME    [Toc]    [Back]

       pthread_once  - Calls a routine to be executed by a single
       thread, once.

SYNOPSIS    [Toc]    [Back]

       #include <pthread.h>

       int pthread_once(
               pthread_once_t *once_control,
               void (*routine)(void) );

LIBRARY    [Toc]    [Back]

       DECthreads POSIX 1003.1c Library (libpthread.so)

STANDARDS    [Toc]    [Back]

       Interfaces documented on this reference  page  conform  to
       industry standards as follows:

       IEEE  Std  1003.1c-1995,  POSIX System Application Program
       Interface

PARAMETERS    [Toc]    [Back]

       Address of a record that controls the  one-time  execution
       code.  Each  one-time  execution routine must have its own
       unique pthread_once_t record.  Address of a  procedure  to
       be  executed  once.  This  routine  is  called  only once,
       regardless of the number of times it  and  its  associated
       once_control block are passed to pthread_once(3).

DESCRIPTION    [Toc]    [Back]

       The  first call to this routine by any thread in a process
       with a given once_control will call the specified  routine
       with  no  arguments.  Subsequent  calls to pthread_once(3)
       with the same once_control will not call the  routine.  On
       return  from  pthread_once(3),  it  is guaranteed that the
       routine has completed.

       For example, a mutex or a per-thread context key  must  be
       created exactly once. Calling pthread_once(3) ensures that
       the initialization is serialized across multiple  threads.
       Other  threads that reach the same point in the code would
       be delayed until the first thread is finished.

       If you specify  a  routine  that  directly  or  indirectly
       results  in  a  recursive call to pthread_once(3) and that
       specifies the same routine argument,  the  recursive  call
       can result in a deadlock.

       To  initialize  the  once_control record, your program can
       zero  out  the  entire  structure,  or  you  can  use  the
       PTHREAD_ONCE_INIT macro, which is defined in the pthread.h
       header file, to statically initialize that  structure.  If
       using  PTHREAD_ONCE_INIT,  declare the once_control record
       as follows:

       pthread_once_t  once_control= PTHREAD_ONCE_INIT;

       Note that it is often easier to simply lock  a  statically
       initialized  mutex, check a control flag, and perform necessary
  initialization   (in-line)   rather   than   using
       pthread_once(3).  For example, code an initialization routine
 that begins with the following basic logic:

       init() {
        static pthread_mutex_t    mutex =  PTHREAD_MUTEX_INITIALIZER;

        static int                flag = FALSE;

        pthread_mutex_lock(&mutex);
        if(!flag)
          {
           flag = TRUE;
           /* initialize code */
          }
        pthread_mutex_unlock(&mutex); }

RETURN VALUES    [Toc]    [Back]

       If  an  error  condition  occurs,  this routine returns an
       integer indicating the type of error. Possible return values
  are as follows: Successful completion.  Invalid argument.

ERRORS    [Toc]    [Back]

       None

SEE ALSO    [Toc]    [Back]

      
      
       Manuals: Guide to DECthreads and Programmer's Guide



                                                  pthread_once(3)
[ Back ]
 Similar pages
Name OS Title
tis_once Tru64 Calls an initialization routine that can be executed by only one thread, once
pthread_cleanup_push Tru64 (Macro) Establishes a cleanup handler routine to be executed when the thread exits or is canceled
HTRID3 IRIX EISPACK routine. This subroutine reduces a COMPLEX HERMITIAN matrix, stored as a single square array, to a rea
pthread_kill Tru64 Delivers a signal to a specified thread. (This routine is available only on a UNIX system.)
atom_application_instrumentation Tru64 Allows an Atom tool's instrumentation routine to add, within an application program, calls to analys...
ReplaceEntry Tru64 Allows an Atom tool's instrumentation routine to add, within an application program, calls to analys...
ReplaceProto Tru64 Allows an Atom tool's instrumentation routine to add, within an application program, calls to analys...
AddCallEntry Tru64 Allows an Atom tool's instrumentation routine to add, within an application program, calls to analys...
AddCallProc Tru64 Allows an Atom tool's instrumentation routine to add, within an application program, calls to analys...
AddCallProgram Tru64 Allows an Atom tool's instrumentation routine to add, within an application program, calls to analys...
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service