Threads Debugging Library Functions tdtaeventaddr(3CDB)
NAME
tdtaeventaddr, tdthreventenable, tdtasetevent,
tdthrsetevent, tdtaclearevent, tdthrclearevent,
tdtaeventgetmsg, tdthreventgetmsg, tdeventemptyset,
tdeventfillset, tdeventaddset, tdeventdelset,
tdeventismember, tdeventisempty - thread events in libcdb
SYNOPSIS
cc [ flag... ] file... -lcdb [ library... ]
#include
#include
tderre tdtaeventaddr(const tdthragentt *tap, ulong event,tdnotifyt *notifyp);
tderre tdthreventenable(const tdthrhandlet *thp, int onoff);
tderre tdthrsetevent(const tdthrhandlet *thp, tdthreventst *events);
tderre tdtasetevent(const tdthragentt *tap, tdthreventst *events);
tderre tdthrclearevent(const tdthrhandlet *thp, tdthreventst *events);
tderre tdtaclearevent(const tdthragentt *tap, tdthreventst *events);
tderre tdthreventgetmsg(const tdthrhandlet *thp, tdeventmsgt *msg);
tderre tdtaeventgetmsg(const tdthragentt *tap, tdeventmsgt *msg);
void tdeventemptyset(tdthreventst *);
void tdeventfillset(tdthreventst *);
void tdeventaddset(tdthreventst *, tdthreventse n);
void tdeventdelset(tdthreventst *, tdthreventse n);
void tdeventismember(tdthreventst *, tdthreventse n);
SunOS 5.11 Last change: 19 Oct 1998 1
Threads Debugging Library Functions tdtaeventaddr(3CDB)
void tdeventisempty(tdthreventst*);
DESCRIPTION
These functions comprise the thread event facility for
libcdb(3LIB). This facility allows the controlling process
to be notified when certain thread-related events occur in a
target process and to retrieve information associated with
these events. An event consists of an event type, and
optionally, some associated event data, depending on the
event type. See the section titled "Event Set Manipulation
Macros" that follows.
The event type and the associated event data, if any, con-
stitute an "event message." "Reporting an event" means
delivering an event message to the controlling process by
way of libcdb.
Several flags can control event reporting, both a per-thread
and per event basis. Event reporting may further be enabled
or disabled for a thread. There is not only a per-thread
event mask that specifies which event types should be
reported for that thread, but there is also a global event
mask that applies to all threads.
An event is reported, if and only if, the executing thread
has event reporting enabled, and either the event type is
enabled in the executing thread's event mask, or the event
type is enabled in the global event mask.
Each thread has associated with it an event buffer in which
it stores the most recent event message it has generated,
the type of the most recent event that it reported, and,
depending on the event type, some additional information
related to that event. See the section titled "Event Set
Manipulation Macros" for a description of the
tdthreventse and tdeventmsgt types and a list of the
event types and the values reported with them. The thread
handle, type tdthrhandlet, the event type, and the possi-
ble value, together constitute an event message. Each
thread's event buffer holds at most one event message.
Each event type has an event reporting address associated
with it. A thread reports an event by writing the event
message into the thread's event buffer and having control
reach the event reporting address for that event type.
SunOS 5.11 Last change: 19 Oct 1998 2
Threads Debugging Library Functions tdtaeventaddr(3CDB)
Typically, the controlling process sets a breakpoint at the
event reporting address for one or more event types. When
the breakpoint is hit, the controlling process knows that an
event of the corresponding type has occurred.
The event types, and the additional information, if any,
reported with each event, are:
TDREADY The thread became ready to execute.
TDSLEP The thread has blocked on a synchroniza-
tion object.
TDSWITCHTO A runnable thread is being assigned to
LWP.
TDSWITCHFROM A running thread is being removed from its
LWP.
TDLOCKTRY A thread is trying to get an unavailable
lock.
TDCATCHSIG A signal was posted to a thread.
TDIDLE An LWP is becoming idle.
TDCREATE A thread is being created.
TDEATH A thread has terminated.
TDPREMPT A thread is being preempted.
TDPRINHERIT A thread is inheriting an elevated prior-
ity from another thread.
TDREAP A thread is being reaped.
TDCONCURENCY The number of LWPs is changing.
SunOS 5.11 Last change: 19 Oct 1998 3
Threads Debugging Library Functions tdtaeventaddr(3CDB)
TDTIMEOUT A condition-variable timed wait expired.
The tdtaeventaddr() function returns in *notifyp the
event reporting address associated with event type event.
The controlling process may then set a breakpoint at that
address. If a thread hits that breakpoint, it reports an
event of type event.
The tdthreventenable() function enables or disables event
reporting for thread thp. If a thread has event reporting
disabled, it will not report any events. Threads are started
with event reporting disabled. Event reporting is enabled
if onoff is non-zero; otherwise, it is disabled. To deter-
mine whether or not event reporting is enabled on a thread,
call tdthrgetinfo() for the thread and examine the
titraceme member of the tdthrinfot structure it returns.
The tdthrsetevent() and tdthrclearevent() functions
set and clear, respectively, a set of event types in the
event mask associated with the thread thp. To inspect a
thread's event mask, call tdthrgetinfo() for the thread
and examine the tievents member of the tdthrinfot struc-
ture it returns.
The tdtasetevent() and tdtaclearevent() functions
identical to tdthrsetevent() and tdthrclearevent(),
respectively, except that the target process's global event
mask is modified. There is no provision for inspecting the
value of a target process's global event mask.
The tdthreventgetmsg() function returns in *msg the event
message associated with thread *thp. Reading a thread's
event message consumes the message, emptying the thread's
event buffer. As noted above, each thread's event buffer
holds at most one event message; if a thread reports a
second event before the first event message has been read,
the second event message overwrites the first.
The tdtaeventgetmsg() function is identical to
tdthreventgetmsg(), except that it is passed a process
handle rather than a thread handle. It selects some thread
that has an event message buffered and returns that thread's
message. The thread selected is undefined, except that as
long as at least one thread has an event message buffered,
it returns an event message from some such thread.
SunOS 5.11 Last change: 19 Oct 1998 4
Threads Debugging Library Functions tdtaeventaddr(3CDB)
Event Set Manipulation Macros
Several macros are provided for manipulating event sets of
type tdthreventst:
tdeventemptyset Sets its argument to the NUL event
set.
tdeventfillset Sets its argument to the set of all
events.
tdeventaddset Adds a specific event type to an event
set.
tdeventdelset Deletes a specific event type from an
event set.
tdeventismember Tests whether a specific event type is
a member of an event set.
tdeventisempty Tests whether an event set is the NUL
set.
RETURN VALUES
The following values may be returned for all thread event
routines:
TDOK The call returned successfully.
TDBADTH An invalid thread handle was passed in.
TDBADTA An invalid internal process handle was passed.
TDBADPH There is a NUL external process handle associ-
ated with this internal process handle.
TDBER A call to one of the imported interface routines
failed.
TDNOMSG No event message was available to return to
tdthreventgetmsg() or tdtaeventgetmsg().
SunOS 5.11 Last change: 19 Oct 1998 5
Threads Debugging Library Functions tdtaeventaddr(3CDB)
TDER Some other parameter error occurred, or a
libcdb() internal error occurred.
The following value can be returned for
tdthreventenable(), tdthrsetevent(), and
tdthrclearevent() only:
TDNOCAPAB Because the agent thread in the target pro-
cess has not completed initialization, this
operation cannot be performed. The operation
can be performed after the target process has
been allowed to make some forward progress.
See libcdb(3LIB).
ATRIBUTES
See attributes(5) for description of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level Safe
SEE ALSO
libcdb(3LIB), attributes(5)
SunOS 5.11 Last change: 19 Oct 1998 6
|
