Description

These functions comprise the thread event facility for libc_db(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, constitute
an "event message." "Reporting an event" means delivering an
event message to the controlling process by way of libc_db.

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 td_thr_events_e
and td_event_msg_t types and a list of the event types and the
values reported with them. The thread handle, type td_thrhandle_t, the event type,
and the possible 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.

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:

TD_READY

The thread became ready to execute.

TD_SLEEP

The thread has blocked on a synchronization object.

TD_SWITCHTO

A runnable thread is being assigned to LWP.

TD_SWITCHFROM

A running thread is being removed from its LWP.

TD_LOCK_TRY

A thread is trying to get an unavailable lock.

TD_CATCHSIG

A signal was posted to a thread.

TD_IDLE

An LWP is becoming idle.

TD_CREATE

A thread is being created.

TD_DEATH

A thread has terminated.

TD_PREEMPT

A thread is being preempted.

TD_PRI_INHERIT

A thread is inheriting an elevated priority from another thread.

TD_REAP

A thread is being reaped.

TD_CONCURRENCY

The number of LWPs is changing.

TD_TIMEOUT

A condition-variable timed wait expired.

The td_ta_event_addr() function returns in *notify_p 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 td_thr_event_enable() function enables or disables event reporting for thread th_p. 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 on_off is non-zero; otherwise, it is disabled. To determine whether
or not event reporting is enabled on a thread, call td_thr_getinfo()
for the thread and examine the ti_traceme member of the td_thrinfo_t structure
it returns.

The td_thr_set_event() and td_thr_clear_event() functions set and clear, respectively, a set of
event types in the event mask associated with the thread th_p. To
inspect a thread's event mask, call td_thr_getinfo() for the thread and examine
the ti_events member of the td_thrinfo_t structure it returns.

The td_ta_set_event() and td_ta_clear_event() functions identical to td_thr_set_event() and td_thr_clear_event(), 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 td_thr_event_getmsg() function returns in *msg the event message associated with thread
*th_p. 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 td_ta_event_getmsg() function is identical to td_thr_event_getmsg(), 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.

Event Set Manipulation Macros

Several macros are provided for manipulating event sets of type td_thr_events_t:

td_event_emptyset

Sets its argument to the NULL event set.

td_event_fillset

Sets its argument to the set of all events.

td_event_addset

Adds a specific event type to an event set.

td_event_delset

Deletes a specific event type from an event set.

td_eventismember

Tests whether a specific event type is a member of an event set.

td_eventisempty

Tests whether an event set is the NULL set.

Return Values

The following values may be returned for all thread event routines:

TD_OK

The call returned successfully.

TD_BADTH

An invalid thread handle was passed in.

TD_BADTA

An invalid internal process handle was passed.

TD_BADPH

There is a NULL external process handle associated with this internal process handle.

TD_DBERR

A call to one of the imported interface routines failed.

TD_NOMSG

No event message was available to return to td_thr_event_getmsg() or td_ta_event_getmsg().

TD_ERR

Some other parameter error occurred, or a libc_db() internal error occurred.

The following value can be returned for td_thr_event_enable(), td_thr_set_event(), and td_thr_clear_event() only:

TD_NOCAPAB

Because the agent thread in the target process 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 libc_db(3LIB).