Next: , Previous: Inferiors In Python, Up: Python API


23.2.2.9 Events In Python

gdb provides a general event facility so that Python code can be notified of various state changes, particularly changes that occur in the inferior.

An event is just an object that describes some state change. The type of the object and its attributes will vary depending on the details of the change. All the existing events are described below.

In order to be notified of an event, you must register an event handler with an event registry. An event registry is an object in the gdb.events module which dispatches particular events. A registry provides methods to register and unregister event handlers:

— Method on EventRegistry: connect object

Add the given callable object to the registry. This object will be called when an event corresponding to this registry occurs.

— Method on EventRegistry: disconnect object

Remove the given object from the registry. Once removed, the object will no longer receive notifications of events.

Here is an example:

     def exit_handler (event):
         print "event type: exit"
         print "exit code: %d" % (event.exit_code)
     
     gdb.events.exited.connect (exit_handler)

In the above example we connect our handler exit_handler to the registry events.exited. Once connected, exit_handler gets called when the inferior exits. The argument event in this example is of type gdb.ExitedEvent. As you can see in the example the ExitedEvent object has an attribute which indicates the exit code of the inferior.

The following is a listing of the event registries that are available and details of the events they emit:

events.cont
Emits gdb.ThreadEvent.

Some events can be thread specific when gdb is running in non-stop mode. When represented in Python, these events all extend gdb.ThreadEvent. Note, this event is not emitted directly; instead, events which are emitted by this or other modules might extend this event. Examples of these events are gdb.BreakpointEvent and gdb.ContinueEvent.

— Instance Variable of ThreadEvent: inferior_thread

In non-stop mode this attribute will be set to the specific thread which was involved in the emitted event. Otherwise, it will be set to None.

Emits gdb.ContinueEvent which extends gdb.ThreadEvent.

This event indicates that the inferior has been continued after a stop. For inherited attribute refer to gdb.ThreadEvent above.

events.exited
Emits events.ExitedEvent which indicates that the inferior has exited. events.ExitedEvent has one optional attribute. This attribute will exist only in the case that the inferior exited with some status.
— Instance Variable of ExitedEvent: exit_code

An integer representing the exit code which the inferior has returned.

events.stop
Emits gdb.StopEvent which extends gdb.ThreadEvent.

Indicates that the inferior has stopped. All events emitted by this registry extend StopEvent. As a child of gdb.ThreadEvent, gdb.StopEvent will indicate the stopped thread when gdb is running in non-stop mode. Refer to gdb.ThreadEvent above for more details.

Emits gdb.SignalEvent which extends gdb.StopEvent.

This event indicates that the inferior or one of its threads has received as signal. gdb.SignalEvent has the following attributes:

— Instance Variable of SignalEvent: stop_signal

A string representing the signal received by the inferior. A list of possible signal values can be obtained by running the command info signals in the gdb command prompt.

Also emits gdb.BreakpointEvent which extends gdb.StopEvent.

gdb.BreakpointEvent event indicates that a breakpoint has been hit, and has the following attributes:

— Instance Variable of BreakpointEvent: breakpoint

A reference to the breakpoint that was hit of type gdb.Breakpoint. See Breakpoints In Python, for details of the gdb.Breakpoint object.