* event-loop.h: Mention async_event_handlers.
[deliverable/binutils-gdb.git] / gdb / event-loop.h
CommitLineData
b5a0ac70 1/* Definitions used by the GDB event loop.
9b254dd1 2 Copyright (C) 1999, 2000, 2007, 2008 Free Software Foundation, Inc.
b5a0ac70
SS
3 Written by Elena Zannoni <ezannoni@cygnus.com> of Cygnus Solutions.
4
5 This file is part of GDB.
6
7 This program is free software; you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
a9762ec7 9 the Free Software Foundation; either version 3 of the License, or
b5a0ac70
SS
10 (at your option) any later version.
11
12 This program is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU General Public License for more details.
16
17 You should have received a copy of the GNU General Public License
a9762ec7 18 along with this program. If not, see <http://www.gnu.org/licenses/>. */
b5a0ac70 19
b5a0ac70
SS
20/* An event loop listens for events from multiple event sources. When
21 an event arrives, it is queued and processed by calling the
22 appropriate event handler. The event loop then continues to listen
23 for more events. An event loop completes when there are no event
24 sources to listen on. External event sources can be plugged into
25 the loop.
26
50d01748 27 There are 4 main components:
b5a0ac70 28 - a list of file descriptors to be monitored, GDB_NOTIFIER.
50d01748
PA
29 - a list of asynchronous event sources to be monitored,
30 ASYNC_EVENT_HANDLER_LIST.
b5a0ac70
SS
31 - a list of events that have occurred, EVENT_QUEUE.
32 - a list of signal handling functions, SIGHANDLER_LIST.
33
50d01748
PA
34 GDB_NOTIFIER keeps track of the file descriptor based event
35 sources. ASYNC_EVENT_HANDLER_LIST keeps track of asynchronous
36 event sources that are signalled by some component of gdb, usually
37 a target_ops instance. Event sources for gdb are currently the UI
38 and the target. Gdb communicates with the command line user
39 interface via the readline library and usually communicates with
40 remote targets via a serial port. Serial ports are represented in
41 GDB as file descriptors and select/poll calls. For native targets
42 instead, the communication varies across operating system debug
43 APIs, but usually consists of calls to ptrace and waits (via
44 signals) or calls to poll/select (via file descriptors). In the
45 current gdb, the code handling events related to the target resides
46 in wait_for_inferior for synchronous targets; or, for asynchronous
47 capable targets, by having the target register either a target
48 controlled file descriptor and/or an asynchronous event source in
49 the event loop, with the fetch_inferior_event function as the event
50 callback. In both the synchronous and asynchronous cases, usually
51 the target event is collected through the target_wait interface.
52 The target is free to install other event sources in the event loop
53 if it so requires.
b5a0ac70
SS
54
55 EVENT_QUEUE keeps track of the events that have happened during the
56 last iteration of the event loop, and need to be processed. An
57 event is represented by a procedure to be invoked in order to
58 process the event. The queue is scanned head to tail. If the
59 event of interest is a change of state in a file descriptor, then a
60 call to poll or select will be made to detect it.
61
62 If the events generate signals, they are also queued by special
63 functions that are invoked through traditional signal handlers.
64 The actions to be taken is response to such events will be executed
65 when the SIGHANDLER_LIST is scanned, the next time through the
66 infinite loop.
67
68 Corollary tasks are the creation and deletion of event sources. */
69
97bb9d91 70typedef void *gdb_client_data;
c2c6d25f 71struct async_signal_handler;
50d01748 72struct async_event_handler;
2acceee2 73typedef void (handler_func) (int, gdb_client_data);
c2c6d25f 74typedef void (sig_handler_func) (gdb_client_data);
50d01748 75typedef void (async_event_handler_func) (gdb_client_data);
c2c6d25f 76typedef void (timer_handler_func) (gdb_client_data);
b5a0ac70
SS
77
78/* Where to add an event onto the event queue, by queue_event. */
79typedef enum
80 {
81 /* Add at tail of queue. It will be processed in first in first
82 out order. */
83 TAIL,
84 /* Add at head of queue. It will be processed in last in first out
85 order. */
c5aa993b 86 HEAD
b5a0ac70
SS
87 }
88queue_position;
89
90/* Tell create_file_handler what events we are interested in.
91 This is used by the select version of the event loop. */
92
93#define GDB_READABLE (1<<1)
94#define GDB_WRITABLE (1<<2)
95#define GDB_EXCEPTION (1<<3)
96
085dd6e6 97/* Exported functions from event-loop.c */
0f71a2f6 98
c2c6d25f 99extern void start_event_loop (void);
99656a61 100extern int gdb_do_one_event (void *data);
c2c6d25f 101extern void delete_file_handler (int fd);
6426a772 102extern void add_file_handler (int fd, handler_func * proc, gdb_client_data client_data);
6426a772
JM
103extern struct async_signal_handler *
104 create_async_signal_handler (sig_handler_func * proc, gdb_client_data client_data);
105extern void delete_async_signal_handler (struct async_signal_handler **async_handler_ptr);
6426a772 106extern int create_timer (int milliseconds, timer_handler_func * proc, gdb_client_data client_data);
c2c6d25f 107extern void delete_timer (int id);
b803fb0f
DJ
108
109/* Call the handler from HANDLER immediately. This function
110 runs signal handlers when returning to the event loop would be too
111 slow. Do not call this directly; use gdb_call_async_signal_handler,
112 below, with IMMEDIATE_P == 1. */
113void call_async_signal_handler (struct async_signal_handler *handler);
114
115/* Call the handler from HANDLER the next time through the event loop.
116 Do not call this directly; use gdb_call_async_signal_handler,
117 below, with IMMEDIATE_P == 0. */
118void mark_async_signal_handler (struct async_signal_handler *handler);
119
120/* Wrapper for the body of signal handlers. Call this function from
121 any SIGINT handler which needs to access GDB data structures or
122 escape via longjmp. If IMMEDIATE_P is set, this triggers either
123 immediately (for POSIX platforms), or from gdb_select (for
124 MinGW). If IMMEDIATE_P is clear, the handler will run the next
125 time we return to the event loop and any current select calls
126 will be interrupted. */
127
128void gdb_call_async_signal_handler (struct async_signal_handler *handler,
129 int immediate_p);
50d01748
PA
130
131/* Create and register an asynchronous event source in the event loop,
132 and set PROC as its callback. CLIENT_DATA is passed as argument to
133 PROC upon its invocation. Returns a pointer to an opaque structure
134 used to mark as ready and to later delete this event source from
135 the event loop. */
136extern struct async_event_handler *
137 create_async_event_handler (async_event_handler_func *proc,
138 gdb_client_data client_data);
139
140/* Remove the event source pointed by HANDLER_PTR created by
141 CREATE_ASYNC_EVENT_HANDLER from the event loop, and release it. */
142extern void
143 delete_async_event_handler (struct async_event_handler **handler_ptr);
144
145/* Call the handler from HANDLER the next time through the event
146 loop. */
147extern void mark_async_event_handler (struct async_event_handler *handler);
This page took 0.620321 seconds and 4 git commands to generate.