SunOS man pages : td_sync_get_info (3)
Threads Library Functions td_sync_get_info(3THR)
NAME
td_sync_get_info, td_sync_setstate, td_sync_waiters - opera-
tions on a synchronization object in libthread_db
SYNOPSIS
cc [ flag ... ] file ... -lthread_db [ library ... ]
#include <proc_service.h>
#include <thread_db.h>
td_err_e td_sync_get_info(const td_synchandle_t *sh_p,
td_syncinfo_t *si_p);
td_err_e td_sync_setstate(const td_synchandle_t *sh_p);
td_err_etd_sync_waiters(const td_synchandle_t
*sh_p,td_thr_iter_f *cb,void *cb_data_p);
DESCRIPTION
Synchronization objects include mutexes, condition vari-
ables, semaphores, and reader-writer locks. In the same way
that thread operations use a thread handle of type
td_thrhandle_t, operations on synchronization objects use a
synchronization object handle of type td_synchandle_t.
The controlling process obtains synchronization object han-
dles either by calling the function td_ta_sync_iter() to
obtain handles for all synchronization objects of the target
process that are known to the libthread_db library of
interfaces, or by mapping the address of a synchronization
object in the address space of the target process to a han-
dle by calling
td_ta_map_addr2sync().
Note that not all synchronization objects that a process
uses may be known to the libthread_db library and returned
by td_ta_sync_iter. A synchronization object is known to
libthread_db only if it was ever waited on after
libthread_db was attached to the process. For example, a
mutex may have been widely used, but if no thread ever
blocked waiting to acquire it, it will not be known to
libthread_db interfaces.
The td_sync_get_info() function fills in the td_syncinfo_t
structure *si_p with values for the synchronization object
identified by sh_p. The td_syncinfo_t structure contains
the following fields:
td_thragent_t *si_ta_p
The internal process handle identifying the tar-
get process through which this synchronization
object handle was obtained. Synchronization
SunOS 5.8 Last change: 19 Oct 1998 1
Threads Library Functions td_sync_get_info(3THR)
objects may be process-private or process-shared.
In the latter case, the same synchronization
object may have multiple handles, one for each
target process's "view" of the synchronization
object.
psaddr_t si_sv_addr
The address of the synchronization object in this
target process's address space.
td_sync_type_e si_type
The type of the synchronization variable: mutex,
condition
variable, semaphore, or reader-writer lock.
int si_shared_type
USYNC_THREAD if this synchronization object is
process-private; USYNC_PROCESS if it is
process-shared.
td_sync_flags_t si_flags
Flags dependent on the type of the synchroniza-
tion object.
int si_state.sema_count
Semaphores only. The current value of the sema-
phore
int si_state.nreaders
Reader-writer locks only. The number of readers
currently holding the lock, or -1, if a writer
is currently holding the lock.
int si_state.mutex_locked
For mutexes only. Non-zero if and only if the
mutex is currently locked.
int si_size
The size of the synchronization object.
uchar_t si_has_waiters
Non-zero if and only if at least one thread is
blocked on this synchronization object.
SunOS 5.8 Last change: 19 Oct 1998 2
Threads Library Functions td_sync_get_info(3THR)
uchar_t si_is_wlocked
For reader-writer locks only. The value is non-
zero if and only if this lock is held by a
writer.
td_thrhandle_t si_owner
Mutexes and reader-writer locks only. This is the
thread holding the mutex, or the write lock, if
this is a reader-writer lock. The value is
NULL if no one holds the mutex or write-lock.
psaddr_t si_data
A pointer to optional data associated with the
synchronization object. Currently useful only
for debugging libthread() interfaces.
td_sync_setstate modifies the state of synchronization
object si_p, depending on the synchronization object type.
For mutexes, td_sync_setstate is unlocked if the value is
0. Otherwise it is locked. For semaphores, the semaphore's
count is set to the value. For reader-writer locks, the
reader count set to the value if value is >0. The count is
set to write-locked if value is -1. It is set to unlocked
if the value is 0. Setting the state of a synchronization
object from a libthread_db interface may cause the synchron-
ization object's semantics to be violated from the point of
view of the threads in the target process. For example, if a
thread holds a mutex, and td_sync_setstate is used to set
the mutex to unlocked, then a different thread will also be
able to subsequently acquire the same mutex.
td_sync_waiters iterates over the set of thread handles of
threads blocked on sh_p. The callback function cb is
called once for each such thread handle, and is passed the
thread handle and cb_data_p. If the callback function
returns a non-zero value, iteration is terminated early.
See also td_ta_thr_iter(3THR).
RETURN VALUES
TD_OK The call returned successfully.
TD_BADTH
An invalid thread handle was passed in.
TD_DBERR
A call to one of the imported interface routines
failed.
TD_ERR
SunOS 5.8 Last change: 19 Oct 1998 3
Threads Library Functions td_sync_get_info(3THR)
A libthread_db-internal error occurred.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| MT Level | Safe |
|_____________________________|_____________________________|
SEE ALSO
libthread_db(3THR), td_ta_map_addr2sync(3THR),
td_ta_sync_iter(3THR), td_ta_thr_iter(3THR),
libthread_db(3LIB), attributes(5)
SunOS 5.8 Last change: 19 Oct 1998 4
|
 |
|
|
