Threads Debugging Library Functions tdsyncgetinfo(3CDB)
NAME
tdsyncgetinfo, tdtasynctrackingenable,
tdsyncgetstats, tdsyncsetstate, tdsyncwaiters -
operations on a synchronization object in libcdb
SYNOPSIS
cc [ flag... ] file... -lcdb [ library... ]
#include
#include
tderre tdsyncgetinfo(const tdsynchandlet *shp, tdsyncinfot *sip);
tderre tdtasynctrackingenable(const tdthragentt *tap, int onoff);
tderre tdsyncgetstats(const tdsynchandlet *shp, tdsyncstatst *ssp);
tderre tdsyncsetstate(const tdsynchandlet *shp);
typedef int tdthriterf(const tdthrhandlet *thp, void *cbdatap);
tderre tdsyncwaiters(const tdsynchandlet *shp, tdthriterf *cb,
void *cbdatap);
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
tdthrhandlet, operations on synchronization objects use a
synchronization object handle of type tdsynchandlet.
The controlling process obtains synchronization object han-
dles either by calling the function tdtasynciter() to
obtain handles for all synchronization objects of the target
process that are known to the libcdb library of interfaces,
or by mapping the address of a synchronization object in the
address space of the target process to a handle by calling
tdtamapaddr2sync(3CDB).
Not all synchronization objects that a process uses can be
known to the libcdb library and returned by
tdtasynciter(3CDB). A synchronization object is known to
libcdb only if it has been the target of a synchronization
primitive in the process (such as mutexlock(), described on
the mutexinit(3C) manual page) after tdtanew(3CDB) has
SunOS 5.11 Last change: 5 Jun 2007 1
Threads Debugging Library Functions tdsyncgetinfo(3CDB)
been called to attach to the process and
tdtasynctrackingenable() has been called to enable syn-
chronization object tracking.
The tdtasynctrackingenable() function turns synchroniza-
tion object tracking on or off for the process identified by
tap, depending on whether onoff is 0 (off) or non-zero
(on).
The tdsyncgetinfo() function fills in the tdsyncinfot
structure *sip with values for the synchronization object
identified by shp. The tdsyncinfot structure contains
the following fields:
tdthragentt *sitap The internal process handle
identifying the target process
through which this synchroniza-
tion object handle was
obtained. Synchronization
objects may be process-private
or process-shared. In the
latter case, the same synchron-
ization object may have multi-
ple handles, one for each tar-
get process's "view" of the
synchronization object.
psaddrt sisvaddr The address of the synchroniza-
tion object in this target
process's address space.
tdsynctypee sitype The type of the synchronization
variable: mutex, condition
variable, semaphore, or
readers-writer lock.
int sisharedtype If sisharedtype is non-zero,
this synchronization object is
process-shared, otherwise it is
process-private.
tdsyncflagst siflags Flags dependent on the type of
the synchronization object.
SunOS 5.11 Last change: 5 Jun 2007 2
Threads Debugging Library Functions tdsyncgetinfo(3CDB)
int sistate.semacount Semaphores only. The current
value of the semaphore
int sistate.nreaders Readers-writer locks only. The
number of readers currently
holding the lock, or -1, if a
writer is currently holding the
lock.
int sistate.mutexlocked For mutexes only. Non-zero if
and only if the mutex is
currently locked.
int sisize The size of the synchronization
object.
uint8t sihaswaiters Non-zero if and only if at
least one thread is blocked on
this synchronization object.
uint8t siiswlocked For reader-writer locks only.
The value is non-zero if and
only if this lock is held by a
writer.
uint8t sircount PTHREADMUTEXRECURSIVE mutexes
only. If the mutex is held, the
recursion count.
uint8t siprioceiling PTHREADPRIOPROTECT protocol
mutexes only. The priority
ceiling.
tdthrhandlet siowner Mutexes and readers-writer
locks only. This is the thread
holding the mutex, or the write
lock, if this is a reader-
writer lock. The value is
NUL if no one holds the mutex
or write-lock.
pidt siownerpid Mutexes only. For a locked
process-shared mutex, this is
SunOS 5.11 Last change: 5 Jun 2007 3
Threads Debugging Library Functions tdsyncgetinfo(3CDB)
the process-ID of the process
containing the owning thread.
The tdsyncgetstats() function fills in the tdsyncstatst
structure *ssp with values for the synchronization object
identified by shp. The tdsyncstatst structure contains
an embedded tdsyncinfot structure that is filled in as
described above for tdsyncgetinfo(). In addition, usage
statistics gathered since tdtasynctrackingenable() was
called to enable synchronization object tracking are
returned in the ssun.mutex, ssun.cond, ssun.rwlock, or
ssun.sema members of the tdsyncstatst structure, depend-
ing on the type of the synchronization object.
The tdsyncsetstate function modifies the state of syn-
chronization object sip, depending on the synchronization
object type. For mutexes, tdsyncsetstate 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 syn-
chronization object from a libcdb interface may cause the
synchronization 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 tdsyncsetstate is
used to set the mutex to unlocked, then a different thread
will also be able to subsequently acquire the same mutex.
The tdsyncwaiters function iterates over the set of thread
handles of threads blocked on shp. The callback function cb
is called once for each such thread handle, and is passed
the thread handle and cbdatap. If the callback function
returns a non-zero value, iteration is terminated early. See
tdtathriter(3CDB).
RETURN VALUES
TDOK The call returned successfully.
TDBADTH An invalid thread handle was passed in.
TDBER A call to one of the imported interface rou-
tines failed.
SunOS 5.11 Last change: 5 Jun 2007 4
Threads Debugging Library Functions tdsyncgetinfo(3CDB)
TDER A libcdb-internal error occurred.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level Safe
SEE ALSO
libcdb(3LIB), mutexinit(3C), tdtamapaddr2sync(3CDB),
tdtasynciter(3CDB), tdtathriter(3CDB), attributes(5)
SunOS 5.11 Last change: 5 Jun 2007 5
|
