Guide to DECthreads

int
tis_mutex_trylock (
pthread_mutex_t *mutex);

ARGUMENTS

mutex

Address of the mutex (passed by reference) to be locked.

DESCRIPTION

This routine attempts to lock a mutex. When this routine is called, an attempt is made to immediately lock the mutex. If the mutex is successfully locked, zero (0) is returned.

If the specified mutex is locked when this routine is called, the caller does not wait for the mutex to become available. [EBUSY] is returned, and the thread does not wait to acquire the lock.

Associated Routines

• tis_mutex_destroy()
• tis_mutex_init()
• tis_mutex_lock()
• tis_mutex_unlock()

Unlocks a mutex.

Syntax

tis_mutex_unlock(
mutex );

Argument	Data Type	Access
mutex	opaque pthread_mutex_t	read

int
tis_mutex_unlock (
pthread_mutex_t *mutex);

ARGUMENTS

mutex

Address of the mutex (passed by reference) which is to be unlocked.

DESCRIPTION

This routine unlocks a mutex.

For more information about actions when threads are present, refer to the pthread_mutex_unlock() description.

Associated Routines

• tis_mutex_destroy()
• tis_mutex_init()
• tis_mutex_lock()
• tis_mutex_trylock()

Calls a one-time initialization routine that can be executed by only one thread, once.

Syntax

tis_once(
once _control,
init _routine );

Argument	Data Type	Access
once_control	opaque pthread_once_t	modify
init_routine	procedure	read

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

ARGUMENTS

once_control

Address of a record (control block) that defines the one-time initialization code. Each one-time initialization routine in static storage must have its own unique pthread_once_t record.

init_routine

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().

DESCRIPTION

The first call to this routine by a process with a given once_control will call the init_routine with no arguments. Then subsequent calls to tis_once() with the same once_control will not call the init_routine. On return from tis_once(), 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() ensures that the initialization is serialized across multiple threads.

The once_control variable 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() and that specifies the same init_block argument, the recursive call will result in a deadlock.

---

The PTHREAD_ONCE_INIT macro, defined in the tis.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 flag, and perform necessary initialization (in-line) rather than using tis_once(). For example, you can code an "init" routine that begins tith the following basic logic:

  init() 
  { 
   static pthread_mutex_t    mutex = PTHREAD_MUTEX_INIT; 
   static int                flag = FALSE; 
   
   tis_mutex_lock(&mutex); 
   if(!flag) 
     { 
      flag = TRUE; 
      /* initialize code */ 
     } 
   tis_mutex_unlock(&mutex); 
  } 
   

Acquires a readers/writer lock in read access mode.

Syntax

tis_read_lock(
lock );

Argument	Data Type	Access
lock	opaque tis_rwlock_t	write

int
tis_read_lock (
tis_rwlock_t *lock);

ARGUMENTS

lock

Address of the readers/writer lock.

DESCRIPTION

This routine acquires a readers/writer lock in read access mode. This routine waits for any existing write access mode lock holder to relinquish its lock before granting the lock in read access mode. It returns when the lock is acquired. If the lock is already held in read access mode, the lock is granted.

For each call to tis_read_lock() that successfully acquires the lock in read access mode, a corresponding call tis_read_unlock() must be issued.

Note that the type tis_rwlock_p is a pointer to type tis_rwlock_t.

Associated Routines

• tis_read_trylock()
• tis_read_unlock()
• tis_rwlock_destroy()
• tis_rwlock_init()
• tis_write_lock()
• tis_write_trylock()
• tis_write_unlock()

Attempts to acquire a readers/writer lock in read access mode. Does not wait if the lock cannot be immediately granted.

Syntax

tis_read_trylock(
lock );

Argument	Data Type	Access
lock	opaque tis_rwlock_t	write

int
tis_read_trylock (
tis_rwlock_t *lock);

ARGUMENTS

lock

Address of the readers/writer lock.

DESCRIPTION

This routine attempts to acquire a readers/writer lock in read access mode. If the lock cannot be granted, the routine returns without waiting.

When a thread calls this routine, an attempt is made to immediately acquire the lock in read mode. If the lock is acquired, zero (0) is returned. If a write access mode lock holder exists, [EBUSY] is returned.

If the lock cannot be obtained immediately, the calling program does not wait for the lock to be released.

Associated Routines

• tis_read_lock()
• tis_read_unlock()
• tis_rwlock_destroy()
• tis_rwlock_init()
• tis_write_lock()
• tis_write_trylock()
• tis_write_unlock()

Unlocks a readers/writer lock that was acquired in read access mode.

Syntax

tis_read_unlock(
lock );

Argument	Data Type	Access
lock	opaque tis_rwlock_t	write

int
tis_read_unlock (
tis_rwlock_t *lock);

ARGUMENTS

lock

Address of the readers/writer lock.

DESCRIPTION

This routine unlocks a readers/writer lock that was acquired in read access mode. If there are no other holders of the lock with read access mode and another thread is waiting to acquire the lock in write access mode, the lock will now be granted.

Associated Routines

• tis_read_lock()
• tis_read_trylock()
• tis_rwlock_destroy()
• tis_rwlock_init()
• tis_write_lock()
• tis_write_trylock()
• tis_write_unlock()

Destroys a readers/writer lock.

Syntax

tis_rwlock_destroy(
lock );

Argument	Data Type	Access
lock	opaque tis_rwlock_t	write

int
tis_rwlock_destroy (
tis_rwlock_t *lock);

ARGUMENTS

lock

Address of the readers/writer lock structure to be destroyed.

DESCRIPTION

This routine destroys a readers/writer lock. The routine has the reverse operation of the tis_rwlock_init() routine, which began the session by initializing the tis_rwlock_t structure.

Ensure that there are no locks granted, or threads waiting for locks to be granted, prior to calling this routine.

This routine should be called only after the readers and writer are done using the lock.

Associated Routines

• tis_read_lock()
• tis_read_trylock()
• tis_read_unlock()
• tis_rwlock_init()
• tis_write_lock()
• tis_write_trylock()
• tis_write_unlock()

Initializes a readers/writer lock.

Syntax

tis_rwlock_init(
lock );

Argument	Data Type	Access
lock	opaque tis_rwlock_t	write

int
tis_rwlock_init (
tis_rwlock_t *lock);

ARGUMENTS

lock

Address of a readers/writer lock structure.

DESCRIPTION

This routine initializes a readers/writer lock. The routine initializes the tis_rwlock_t structure that holds the lock states.

To destroy a readers/writer lock, call the tis_rwlock_destroy() routine.

Associated Routines

• tis_read_lock()
• tis_read_trylock()
• tis_read_unlock()
• tis_rwlock_destroy()
• tis_write_lock()
• tis_write_trylock()
• tis_write_unlock()

Obtains the identifier of the current thread.

Syntax

tis_self(
void);

pthread_t
tis_self (void);

ARGUMENTS

None

DESCRIPTION

This routine allows a thread to obtain its own thread identifier.

This value becomes meaningless when the thread is deleted.

The initial thread in a process can "change identity" when thread system initialization completes---that is, when the DECthreads multithreading run-time environment is loaded.

Associated Routines

• pthread_create()

Sets the caller's cancelability state.

Syntax

tis_setcancelstate(
state ,
oldstate );

Argument	Data Type	Access
state	integer	read
oldstate	integer	write

int
tis_setcancelstate (
int state,
int *oldstate );

ARGUMENTS

state

State of general cancelability to set for the calling thread. Valid state values are as follows:

• PTHREAD_CANCEL_ENABLE
• PTHREAD_CANCEL_DISABLE

oldstate

Previous cancelability state.

DESCRIPTION

This routine sets the caller's cancelability state to the value specified in the state argument and returns the previous cancelability state to the location referenced by the oldstate argument.

When cancelability state is set to PTHREAD_CANCEL_DISABLE, a cancelation request cannot be delivered to the thread, even if a cancelable routine is called or asynchronous cancelability is enabled.

When a thread is created, its default cancelability state is PTHREAD_CANCEL_ENABLE. When this routine is called prior to loading threads, the cancel state propagates to the initial thread in the executing program.

Possible Problems When Disabling Cancelability

The most important use of a cancelation request is to ensure that indefinite wait operations are terminated. For example, a thread waiting on some network connection, which may take days to respond (or may never respond), should be made cancelable.

When cancelability state is disabled, no routine is cancelable. As a result, the user is unable to cancel the operation. When disabling cancelability, be sure that no long waits can occur or that it is necessary for other reasons to defer cancelation requests around that particular region of code.

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

Return	Description
0	Successful completion.
[EINVAL]	The specified state is not PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE.

Associated Routines

• tis_testcancel()

Sets the value associated with the specified thread-specific data key.

Syntax

tis_setspecific(
key ,
value );

Argument	Data Type	Access
key	opaque pthread_key_t	read
value	void *	read

int
tis_setspecific (
pthread_key_t key,
const void *value);

ARGUMENTS

key

Thread-specific data key that identifies the data to receive value. Must be obtained from tis_key_create().

value

New value to associate with the specified key. Once set, this value can be retrieved using the same key in a call to tis_getspecific().

DESCRIPTION

This routine sets the value associated with the specified thread-specific data key. If a value is defined for the key (that is, the current value is not NULL), the new value is substituted for it. The key is obtained by a previous call to tis_key_create().

Do not call this routine from a data destructor function.

Return Values If an error condition occurs, this routine returns an integer indicating the type of error. Possible return values are as follows:

Return	Description
0	Successful completion.
[EINVAL]	The key value is invalid.
[ENOMEM]	Insufficient memory exists to associate the value with the key.

Associated Routines

• tis_getspecific()
• tis_key_create()
• tis_key_delete()

Creates a cancelation point in the calling thread.

Syntax

tis_testcancel( );

void
tis_testcancel (void);

ARGUMENTS

None

DESCRIPTION

This routine requests delivery of a pending cancelation request to the calling thread. Thus, this routine creates a cancelation point in the calling thread. The cancelation request is delivered only if a request is pending for the calling thread and the calling thread's cancelability state is enabled. (A thread disables delivery of cancelation requests to itself by calling tis_setcancelstate().)

This routine, when called within very long loops, ensures that a pending cancelation request is noticed within a reasonable amount of time.

Associated Routines

• tis_setcancelstate()

Unlocks the DECthreads global mutex.

Syntax

tis_unlock_global( );

int
tis_unlock_global (void);

ARGUMENTS

None

DESCRIPTION

This routine unlocks the DECthreads global mutex. Because the global mutex is recursive, the unlock will occur when each call to tis_lock_global() has been matched by a call to this routine. For example, if you called tis_lock_global() three times, tis_unlock_global() unlocks the global mutex when you call it the third time.

For more information about actions when threads are present, refer to the pthread_unlock_global_np() description.

Associated Routines

• tis_lock_global()

Acquires a readers/writer lock in write access mode.

Syntax

tis_write_lock(
lock );

Argument	Data Type	Access
lock	opaque tis_rwlock_t	write

int
tis_rwlock (
tis_rwlock_t *lock);

ARGUMENTS

lock

Address of the readers/writer lock.

DESCRIPTION

This routine acquires a readers/writer lock in write access mode. This routine waits for any other active locks (in either read access or write access mode) to become unlocked before the lock request is granted. The routine returns when the readers/writer lock is established.

Associated Routines

• tis_read_lock()
• tis_read_trylock()
• tis_read_unlock()
• tis_rwlock_destroy()
• tis_rwlock_init()
• tis_write_trylock()
• tis_write_unlock()

Attempts to acquire a readers/writer lock in write access mode.

Syntax

tis_write_trylock(
lock );

Argument	Data Type	Access
lock	opaque tis_rwlock_t	write

int
tis_write_trylock (
tis_rwlock_t *lock);

ARGUMENTS

lock

Address of the readers/writer lock.

DESCRIPTION

This routine attempts to acquire a readers/writer lock in write access mode.

An attempt is made to immediately acquire the lock. If the lock is acquired, zero (0) is returned. If the lock is held by another thread (in either read access mode or write access mode), [EBUSY] is returned and the caller does not wait for an eventual lock.

Note that it is a coding error to attempt to acquire the lock in write access mode if the lock is already held by the calling thread. (However, this routine returns [EBUSY] anyway, because no ownership error-checking takes place.)

Associated Routines

• tis_read_lock()
• tis_read_trylock()
• tis_read_unlock()
• tis_rwlock_destroy()
• tis_rwlock_init()
• tis_write_lock()
• tis_write_unlock()

Unlocks a readers/writer lock.

Syntax

tis_write_unlock(
lock );

Argument	Data Type	Access
lock	opaque tis_rwlock_t	write

  6493P014.HTM
  OSSG Documentation
  22-NOV-1996 13:20:17.69

Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal