|
These routines comprise the thread event facility for libthread_db(3THR). 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 libthread_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.
td_ta_event_addr() 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.
td_thr_event_enable() 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 find out whether or not event reporting is enabled on a thread,
call td_thr_getinfo() for the thread and examine the ti_traceme field of the td_thrinfo_t structure it returns.
td_thr_set_event() and td_thr_clear_event() 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 field of the td_thrinfo_t structure
it returns.
td_ta_set_event() and td_ta_clear_event() are just like 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.
td_thr_event_getmsg() 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.
td_ta_event_getmsg() is just like 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 it 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 will return 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.
|
|
