Updated: 11 December 1998 |
Guide to DECthreads
Previous | Contents | Index |
Locks the DECthreads global mutex.
tis_lock_global( );
None
This routine locks the DECthreads global mutex. The global mutex is recursive. 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 taken when threads are present, refer to the pthread_lock_global_np() description.
Return | Description |
---|---|
0 | Successful completion. |
Destroys the specified mutex object.
tis_mutex_destroy(
mutex );
Argument Data Type Access mutex opaque pthread_mutex_t write
mutex
Address of the mutex object (passed by reference) to be destroyed.
This routine destroys a mutex object by uninitializing it, and should be called when a mutex object is no longer referenced. After this routine is called, DECthreads can reclaim internal storage used by the mutex object.It is safe to destroy an initialized mutex object that is unlocked. However, it is illegal to destroy a locked mutex object.
The results of this routine are unpredictable if the mutex object specified in the mutex argument does not currently exist or is not initialized.
Return | Description |
---|---|
0 | Successful completion. |
[EBUSY] | An attempt was made to destroy the object referenced by mutex while it is locked or referenced. |
[EINVAL] | The value specified by mutex is invalid. |
[EPERM] | The caller does not have privileges to perform the operation. |
Initializes the specified mutex object.
tis_mutex_init(
mutex );
Argument Data Type Access mutex opaque pthread_mutex_t write
mutex
Pointer to a mutex object (passed by reference) to be initialized.
This routine initializes a mutex object with the DECthreads default mutex attributes. A mutex is a synchronization object that allows multiple threads to serialize their access to shared data.The mutex object is initialized and set to the unlocked state. Mutexes can be allocated in heap or static memory, but not on a stack.
Your program can use the PTHREAD_MUTEX_INITIALIZER macro to statically initialize a mutex object without calling this routine. Statically initialized mutexes need not be destroyed using tis_mutex_destroy(). Use this macro as follows:
pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;
Return | Description |
---|---|
0 | Successful completion. |
[EAGAIN] | The system lacks the necessary resources to initialize a mutex. |
[ENOMEM] | Insufficient memory exists to initialize the mutex. |
[EBUSY] | The implementation has detected an attempt to reinitialize mutex (a previously initialized, but not yet destroyed, mutex). |
[EINVAL] | The value specified by mutex is invalid. |
[EPERM] | The caller does not have privileges to perform this operation. |
Locks an unlocked mutex.
tis_mutex_lock(
mutex );
Argument Data Type Access mutex opaque pthread_mutex_t read
mutex
Address of the mutex (passed by reference) to be locked.
This routine locks the specified mutex mutex. A deadlock can result if the owner of a mutex calls this routine in an attempt to lock the same mutex a second time. (DECthreads does not detect or report the deadlock.)In a threaded environment, the thread that has locked a mutex becomes its current owner and remains the owner until the same thread has unlocked it. This routine returns with the mutex in the locked state and with the current thread as the mutex's current owner.
Return | Description |
---|---|
0 | Successful completion. |
[EINVAL] | The value specified by mutex is invalid. |
[EDEADLK] | A deadlock condition is detected. |
Attempts to lock the specified mutex.
tis_mutex_trylock(
mutex );
Argument Data Type Access mutex opaque pthread_mutex_t read
mutex
Address of the mutex (passed by reference) to be locked.
This routine attempts to lock the specified mutex mutex. When this routine is called, an attempt is made immediately to lock the mutex. If the mutex is successfully locked, zero (0) is returned.If the specified mutex is already 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.
Return | Description |
---|---|
0 | Successful completion. |
[EBUSY] | The mutex is already locked; therefore, it was not acquired. |
[EINVAL] | The value specified by mutex is invalid. |
Unlocks the specified mutex.
tis_mutex_unlock(
mutex );
Argument Data Type Access mutex opaque pthread_mutex_t read
mutex
Address of the mutex (passed by reference) to be unlocked.
This routine unlocks the specified mutex mutex.For more information about actions taken when threads are present, refer to the pthread_mutex_unlock() description.
Return | Description |
---|---|
0 | Successful completion. |
[EINVAL] | The value specified by mutex is invalid. |
[EPERM] | The caller does not own the mutex. |
Calls a one-time initialization routine that can be executed by only one thread, once.
tis_once(
once _control,
init _routine );
Argument Data Type Access once_control opaque pthread_once_t modify init_routine procedure read
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().
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() with the same once_control do 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 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() 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 flag, and perform necessary initialization (in-line) rather than using tis_once(). 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 flag = FALSE; tis_mutex_lock(&mutex); if(!flag) { flag = TRUE; /* initialize code */ } tis_mutex_unlock(&mutex); }
Return | Description |
---|---|
0 | Successful completion. |
[EINVAL] | Invalid argument. |
Acquires a read-write lock for read access.
tis_read_lock(
lock );
Argument Data Type Access lock opaque tis_rwlock_t write
lock
Address of the read-write lock.
This routine acquires a read-write lock for read access. This routine waits for any existing lock holder for write access to relinquish its lock before granting the lock for read access. This routine returns when the lock is acquired. If the lock is already held for read access, the lock is granted.For each call to tis_read_lock() that successfully acquires the lock for read access, a corresponding call to tis_read_unlock() must be issued.
Note that the type tis_rwlock_p is a pointer to type tis_rwlock_t.
Return | Description |
---|---|
0 | Successful completion. |
[EINVAL] | The value specified by lock is invalid. |
Attempts to acquire a read-write lock for read access. Does not wait if the lock cannot be immediately granted.
tis_read_trylock(
lock );
Argument Data Type Access lock opaque tis_rwlock_t write
lock
Address of the read-write lock to be acquired.
This routine attempts to acquire a read-write lock for read access. 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 for read access. If the lock is acquired, zero (0) is returned. If a holder of the lock for write access exists, [EBUSY] is returned.
If the lock cannot be acquired for read access immediately, the calling program does not wait for the lock to be released.
Return | Description |
---|---|
0 | Successful completion; the lock was acquired. |
[EBUSY] | The lock is being held for write access. The lock for read access was not acquired. |
Unlocks a read-write lock that was acquired for read access.
tis_read_unlock(
lock );
Argument Data Type Access lock opaque tis_rwlock_t write
lock
Address of the read-write lock to be unlocked.
This routine unlocks a read-write lock that was acquired for read access. If there are no other holders of the lock for read access and another thread is waiting to acquire the lock for write access, that lock acquisition is granted.
Return | Description |
---|---|
0 | Successful completion. |
[EINVAL] | The value specified by lock is invalid. |
Destroys the specified read-write lock object.
tis_rwlock_destroy(
lock );
Argument Data Type Access lock opaque tis_rwlock_t write
lock
Address of the read-write lock object to be destroyed.
This routine destroys the specified read-write lock object. Prior to calling this routine, ensure that there are no locks granted to the specified read-write lock and that there are no threads waiting for pending lock acquisitions on the specified read-write lock.This routine should be called only after all reader threads (and perhaps one writer thread) have finished using the specified read-write lock.
Return | Description |
---|---|
0 | Successful completion. |
[EBUSY] | The lock is in use. |
Previous | Next | Contents | Index |
Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal |
6101PRO_027.HTML
|