]> git.ipfire.org Git - thirdparty/binutils-gdb.git/blame - gdb/event-loop.h
import gdb-1999-07-07 post reformat
[thirdparty/binutils-gdb.git] / gdb / event-loop.h
CommitLineData
b5a0ac70
SS
1/* Definitions used by the GDB event loop.
2 Copyright 1999 Free Software Foundation, Inc.
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
9 the Free Software Foundation; either version 2 of the License, or
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
18 along with this program; if not, write to the Free Software
c5aa993b
JM
19 Foundation, Inc., 59 Temple Place - Suite 330,
20 Boston, MA 02111-1307, USA. */
b5a0ac70 21
b5a0ac70
SS
22/* An event loop listens for events from multiple event sources. When
23 an event arrives, it is queued and processed by calling the
24 appropriate event handler. The event loop then continues to listen
25 for more events. An event loop completes when there are no event
26 sources to listen on. External event sources can be plugged into
27 the loop.
28
29 There are 3 main components:
30 - a list of file descriptors to be monitored, GDB_NOTIFIER.
31 - a list of events that have occurred, EVENT_QUEUE.
32 - a list of signal handling functions, SIGHANDLER_LIST.
33
34 GDB_NOTIFIER keeps track of the event sources. Event sources for
35 gdb are currently the UI and the target. Gdb communicates with the
36 command line user interface via the readline library and usually
37 communicates with remote targets via a serial port. Serial ports
38 are represented in GDB as file descriptors and select/poll calls.
39 For native targets instead, the communication consists of calls to
40 ptrace and waits (via signals) or calls to poll/select (via file
41 descriptors). In the current gdb, the code handling events related
42 to the target resides in the wait_for_inferior function and in
43 various target specific files (*-tdep.c).
44
45 EVENT_QUEUE keeps track of the events that have happened during the
46 last iteration of the event loop, and need to be processed. An
47 event is represented by a procedure to be invoked in order to
48 process the event. The queue is scanned head to tail. If the
49 event of interest is a change of state in a file descriptor, then a
50 call to poll or select will be made to detect it.
51
52 If the events generate signals, they are also queued by special
53 functions that are invoked through traditional signal handlers.
54 The actions to be taken is response to such events will be executed
55 when the SIGHANDLER_LIST is scanned, the next time through the
56 infinite loop.
57
58 Corollary tasks are the creation and deletion of event sources. */
59
60typedef PTR gdb_client_data;
61typedef struct gdb_event gdb_event;
62
63typedef void (file_handler_func) PARAMS ((gdb_client_data, int mask));
64typedef void (async_handler_func) PARAMS ((gdb_client_data));
65typedef void (event_handler_func) PARAMS ((int));
66
67/* Event for the GDB event system. Events are queued by calling
68 async_queue_event and serviced later on by gdb_do_one_event. An
69 event can be, for instance, a file descriptor becoming ready to be
70 read. Servicing an event simply means that the procedure PROC will
71 be called. We have 2 queues, one for file handlers that we listen
72 to in the event loop, and one for the file handlers+events that are
73 ready. The procedure PROC associated with each event is always the
74 same (handle_file_event). Its duty is to invoke the handler
75 associated with the file descriptor whose state change generated
76 the event, plus doing other cleanups adn such. */
77
78struct gdb_event
79 {
80 event_handler_func *proc; /* Procedure to call to service this event. */
81 int fd; /* File descriptor that is ready. */
82 struct gdb_event *next_event; /* Next in list of events or NULL. */
83 };
84
85/* Information about each file descriptor we register with the event
86 loop. */
87
88typedef struct file_handler
89 {
90 int fd; /* File descriptor. */
91 int mask; /* Events we want to monitor: POLLIN, etc. */
92 int ready_mask; /* Events that have been seen since
93 the last time. */
94 file_handler_func *proc; /* Procedure to call when fd is ready. */
95 gdb_client_data client_data; /* Argument to pass to proc. */
96 struct file_handler *next_file; /* Next registered file descriptor. */
97 }
98file_handler;
99
100/* PROC is a function to be invoked when the READY flag is set. This
101 happens when there has been a signal and the corresponding signal
102 handler has 'triggered' this async_signal_handler for
103 execution. The actual work to be done in response to a signal will
104 be carried out by PROC at a later time, within process_event. This
105 provides a deferred execution of signal handlers.
106 Async_init_signals takes care of setting up such an
107 asyn_signal_handler for each interesting signal. */
108
109typedef struct async_signal_handler
110 {
c5aa993b 111 int ready; /* If ready, call this handler from the main event loop,
b5a0ac70
SS
112 using invoke_async_handler. */
113 struct async_signal_handler *next_handler; /* Ptr to next handler */
114 async_handler_func *proc; /* Function to call to do the work */
115 gdb_client_data client_data; /* Argument to async_handler_func */
116 }
117async_signal_handler;
118
119/* Where to add an event onto the event queue, by queue_event. */
120typedef enum
121 {
122 /* Add at tail of queue. It will be processed in first in first
123 out order. */
124 TAIL,
125 /* Add at head of queue. It will be processed in last in first out
126 order. */
c5aa993b 127 HEAD
b5a0ac70
SS
128 }
129queue_position;
130
131/* Tell create_file_handler what events we are interested in.
132 This is used by the select version of the event loop. */
133
134#define GDB_READABLE (1<<1)
135#define GDB_WRITABLE (1<<2)
136#define GDB_EXCEPTION (1<<3)
137
138/* Type of the mask arguments to select. */
139
140#ifndef NO_FD_SET
141#define SELECT_MASK fd_set
142#else
143#ifndef _AIX
144typedef long fd_mask;
145#endif
146#if defined(_IBMR2)
147#define SELECT_MASK void
148#else
149#define SELECT_MASK int
150#endif
151#endif
152
153/* Define "NBBY" (number of bits per byte) if it's not already defined. */
154
155#ifndef NBBY
156#define NBBY 8
157#endif
158
159
160/* Define the number of fd_masks in an fd_set */
161
162#ifndef FD_SETSIZE
163#ifdef OPEN_MAX
164#define FD_SETSIZE OPEN_MAX
165#else
166#define FD_SETSIZE 256
167#endif
168#endif
169#if !defined(howmany)
170#define howmany(x, y) (((x)+((y)-1))/(y))
171#endif
172#ifndef NFDBITS
173#define NFDBITS NBBY*sizeof(fd_mask)
174#endif
175#define MASK_SIZE howmany(FD_SETSIZE, NFDBITS)
176
177
178/* Stack for prompts. Each prompt is composed as a prefix, a prompt
179 and a suffix. The prompt to be displayed at any given time is the
180 one on top of the stack. A stack is necessary because of cases in
181 which the execution of a gdb command requires further input from
182 the user, like for instance 'commands' for breakpoints and
183 'actions' for tracepoints. In these cases, the prompt is '>' and
184 gdb should process input using the asynchronous readline interface
185 and the event loop. In order to achieve this, we need to save
186 somewhere the state of GDB, i.e. that it is processing user input
187 as part of a command and not as part of the top level command loop.
188 The prompt stack represents part of the saved state. Another part
189 would be the function that readline would invoke after a whole line
190 of input has ben entered. This second piece would be something
191 like, for instance, where to return within the code for the actions
192 commands after a line has been read. This latter portion has not
193 beeen implemented yet. The need for a 3-part prompt arises from
194 the annotation level. When this is set to 2, the prompt is actually
195 composed of a prefix, the prompt itself and a suffix. */
196
197/* At any particular time there will be always at least one prompt on
198 the stack, the one being currently displayed by gdb. If gdb is
199 using annotation level equal 2, there will be 2 prompts on the
200 stack: the usual one, w/o prefix and suffix (at top - 1), and the
201 'composite' one with prefix and suffix added (at top). At this
202 time, this is the only use of the prompt stack. Resetting annotate
203 to 0 or 1, pops the top of the stack, resetting its size to one
204 element. The MAXPROMPTS limit is safe, for now. Once other cases
205 are dealt with (like the different prompts used for 'commands' or
206 'actions') this array implementation of the prompt stack may have
207 to change. */
208
209#define MAXPROMPTS 10
210struct prompts
211 {
212 struct
213 {
214 char *prefix;
215 char *prompt;
216 char *suffix;
217 }
218 prompt_stack[MAXPROMPTS];
219 int top;
220 };
221
222#define PROMPT(X) the_prompts.prompt_stack[the_prompts.top + X].prompt
223#define PREFIX(X) the_prompts.prompt_stack[the_prompts.top + X].prefix
224#define SUFFIX(X) the_prompts.prompt_stack[the_prompts.top + X].suffix
225
085dd6e6 226/* Exported functions from event-loop.c */
0f71a2f6 227
085dd6e6 228extern void start_event_loop PARAMS ((void));
b5a0ac70 229extern void delete_file_handler PARAMS ((int));
085dd6e6 230extern void add_file_handler PARAMS ((int, file_handler_func, gdb_client_data));
b5a0ac70
SS
231extern void mark_async_signal_handler PARAMS ((async_signal_handler *));
232extern async_signal_handler *
233 create_async_signal_handler PARAMS ((async_handler_func *, gdb_client_data));
c5aa993b 234extern void delete_async_signal_handler PARAMS ((async_signal_handler ** async_handler_ptr));
085dd6e6
JM
235
236/* Exported functions from event-top.c.
237 FIXME: these should really go into top.h. */
238
c5aa993b 239extern void display_gdb_prompt PARAMS ((char *));
392a587b 240extern void async_init_signals PARAMS ((void));
392a587b
JM
241extern void set_async_editing_command PARAMS ((char *, int, struct cmd_list_element *));
242extern void set_async_annotation_level PARAMS ((char *, int, struct cmd_list_element *));
243extern void set_async_prompt PARAMS ((char *, int, struct cmd_list_element *));
0f71a2f6 244extern void handle_stop_sig PARAMS ((int));
43ff13b4
JM
245extern void handle_sigint PARAMS ((int));
246extern void pop_prompt PARAMS ((void));
247extern void push_prompt PARAMS ((char *, char *, char *));
085dd6e6 248extern void gdb_readline2 PARAMS ((void));
0f71a2f6 249
085dd6e6
JM
250/* Exported variables from event-top.c.
251 FIXME: these should really go into top.h. */
0f71a2f6
JM
252
253extern int async_command_editing_p;
254extern char *async_annotation_suffix;
255extern char *new_async_prompt;
256extern struct prompts the_prompts;
085dd6e6
JM
257extern void (*call_readline) PARAMS ((void));
258extern void (*input_handler) PARAMS ((char *));
9846de1b 259extern int input_fd;