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

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

tis_once(3)

Contents


NAME    [Toc]    [Back]

       tis_once  -  Calls  an  initialization routine that can be
       executed by only one thread, once

SYNOPSIS    [Toc]    [Back]

       #include <tis.h>

       int tis_once(
               pthread_once_t *once_control,
               void (*init_routine)(void) );

LIBRARY    [Toc]    [Back]

       Standard C Library (libc.so, libc.a)

STANDARDS    [Toc]    [Back]

       None

PARAMETERS    [Toc]    [Back]

       Address of a record (control block) that defines the  onetime
  initialization  code.  Each  one-time initialization
       routine  in  static  storage  must  have  its  own  unique
       pthread_once_t  record.   Address of a procedure that performs
 the initialization.  This  routine  is  called  only
       once, regardless of the number of times it and its associated
 once_control are passed to tis_once(3).

DESCRIPTION    [Toc]    [Back]

       The first call to this routine by a process with  a  given
       once_control  calls  the  init_routine  with no arguments.
       Thereafter, subsequent calls to tis_once(3) with the  same
       once_control  do not call the init_routine. On return from
       tis_once(3), it is guaranteed that the initialization routine
 has completed.

       For example, a mutex or a thread-specific data key must be
       created exactly once. In a threaded  environment,  calling
       tis_once(3)  ensures that the initialization is serialized
       across multiple threads.

       The once_control argument must be  statically  initialized
       using  the  PTHREAD_ONCE_INIT  macro or by zeroing out the
       entire structure.

       Note If you specify an init_routine that directly or indirectly
 results in a recursive call to tis_once(3) and that
       specifies the same init_block argument, the recursive call
       results in a deadlock.

       The  PTHREAD_ONCE_INIT  macro,  defined in the <pthread.h>
       header file, must be used  to  initialize  a  once_control
       record.  Thus,  your  program  must declare a 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 option, and perform
       necessary  initialization  (in-line)  rather  than   using
       tis_once(3).  For  example, you can code an "init" routine
       that begins with the following basic logic:

         init()   {
          static pthread_mutex_t    mutex = PTHREAD_MUTEX_INIT;
          static int                option = FALSE;

          tis_mutex_lock(&mutex);
          if(!option)
            {
             option = TRUE;
             /* initialize code */
            }
          tis_mutex_unlock(&mutex);
         }

RETURN VALUES    [Toc]    [Back]

       If an error condition  occurs,  this  routine  returns  an
       integer  value  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



                                                      tis_once(3)
[ Back ]
 Similar pages
Name OS Title
pthread_once Tru64 Calls a routine to be executed by a single thread, once.
pthread_cleanup_push Tru64 (Macro) Establishes a cleanup handler routine to be executed when the thread exits or is canceled
pthread_once IRIX thread-safe initialization
sia_init Tru64 initialization routine for SIA (Security Integration Architecture)
siad_init Tru64 initialization routine for SIA (Security Integration Architecture)
pthread_kill Tru64 Delivers a signal to a specified thread. (This routine is available only on a UNIX system.)
AddCallObj 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...
ReplaceProto Tru64 Allows an Atom tool's instrumentation routine to add, within an application program, calls to analys...
AddCallBlock 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