Commit | Line | Data |
---|---|---|
b5a0ac70 | 1 | /* Definitions used by the GDB event loop. |
3666a048 | 2 | Copyright (C) 1999-2021 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 | |
1a5c2598 TT |
20 | #ifndef EVENT_LOOP_H |
21 | #define EVENT_LOOP_H | |
22 | ||
371d5dec | 23 | /* An event loop listens for events from multiple event sources. When |
b5a0ac70 | 24 | an event arrives, it is queued and processed by calling the |
371d5dec MS |
25 | appropriate event handler. The event loop then continues to listen |
26 | for more events. An event loop completes when there are no event | |
b5a0ac70 SS |
27 | sources to listen on. External event sources can be plugged into |
28 | the loop. | |
29 | ||
50d01748 | 30 | There are 4 main components: |
371d5dec | 31 | - a list of file descriptors to be monitored, GDB_NOTIFIER. |
50d01748 PA |
32 | - a list of asynchronous event sources to be monitored, |
33 | ASYNC_EVENT_HANDLER_LIST. | |
371d5dec | 34 | - a list of events that have occurred, EVENT_QUEUE. |
b5a0ac70 SS |
35 | - a list of signal handling functions, SIGHANDLER_LIST. |
36 | ||
50d01748 PA |
37 | GDB_NOTIFIER keeps track of the file descriptor based event |
38 | sources. ASYNC_EVENT_HANDLER_LIST keeps track of asynchronous | |
39 | event sources that are signalled by some component of gdb, usually | |
40 | a target_ops instance. Event sources for gdb are currently the UI | |
41 | and the target. Gdb communicates with the command line user | |
42 | interface via the readline library and usually communicates with | |
43 | remote targets via a serial port. Serial ports are represented in | |
44 | GDB as file descriptors and select/poll calls. For native targets | |
45 | instead, the communication varies across operating system debug | |
46 | APIs, but usually consists of calls to ptrace and waits (via | |
47 | signals) or calls to poll/select (via file descriptors). In the | |
48 | current gdb, the code handling events related to the target resides | |
49 | in wait_for_inferior for synchronous targets; or, for asynchronous | |
50 | capable targets, by having the target register either a target | |
51 | controlled file descriptor and/or an asynchronous event source in | |
52 | the event loop, with the fetch_inferior_event function as the event | |
53 | callback. In both the synchronous and asynchronous cases, usually | |
54 | the target event is collected through the target_wait interface. | |
55 | The target is free to install other event sources in the event loop | |
56 | if it so requires. | |
b5a0ac70 SS |
57 | |
58 | EVENT_QUEUE keeps track of the events that have happened during the | |
59 | last iteration of the event loop, and need to be processed. An | |
60 | event is represented by a procedure to be invoked in order to | |
61 | process the event. The queue is scanned head to tail. If the | |
62 | event of interest is a change of state in a file descriptor, then a | |
63 | call to poll or select will be made to detect it. | |
64 | ||
65 | If the events generate signals, they are also queued by special | |
66 | functions that are invoked through traditional signal handlers. | |
67 | The actions to be taken is response to such events will be executed | |
68 | when the SIGHANDLER_LIST is scanned, the next time through the | |
371d5dec | 69 | infinite loop. |
b5a0ac70 | 70 | |
371d5dec | 71 | Corollary tasks are the creation and deletion of event sources. */ |
b5a0ac70 | 72 | |
97bb9d91 | 73 | typedef void *gdb_client_data; |
2acceee2 | 74 | typedef void (handler_func) (int, gdb_client_data); |
c2c6d25f | 75 | typedef void (timer_handler_func) (gdb_client_data); |
b5a0ac70 | 76 | |
085dd6e6 | 77 | /* Exported functions from event-loop.c */ |
0f71a2f6 | 78 | |
e0dd0826 | 79 | extern int gdb_do_one_event (void); |
c2c6d25f | 80 | extern void delete_file_handler (int fd); |
2554f6f5 SM |
81 | |
82 | /* Add a file handler/descriptor to the list of descriptors we are | |
83 | interested in. | |
84 | ||
85 | FD is the file descriptor for the file/stream to be listened to. | |
86 | ||
6b01403b SM |
87 | NAME is a user-friendly name for the handler. |
88 | ||
89 | If IS_UI is set, this file descriptor is used for a user interface. */ | |
2554f6f5 SM |
90 | |
91 | extern void add_file_handler (int fd, handler_func *proc, | |
92 | gdb_client_data client_data, | |
6b01403b | 93 | std::string &&name, bool is_ui = false); |
2554f6f5 | 94 | |
371d5dec MS |
95 | extern int create_timer (int milliseconds, |
96 | timer_handler_func *proc, | |
97 | gdb_client_data client_data); | |
c2c6d25f | 98 | extern void delete_timer (int id); |
b803fb0f | 99 | |
93b54c8e | 100 | /* Must be defined by client. */ |
b803fb0f | 101 | |
93b54c8e | 102 | extern void handle_event_loop_exception (const gdb_exception &); |
abc56d60 | 103 | |
93b54c8e TT |
104 | /* Must be defined by client. Returns true if any signal handler was |
105 | ready. */ | |
abc56d60 | 106 | |
93b54c8e | 107 | extern int invoke_async_signal_handlers (); |
abc56d60 | 108 | |
93b54c8e TT |
109 | /* Must be defined by client. Returns true if any event handler was |
110 | ready. */ | |
abc56d60 | 111 | |
93b54c8e | 112 | extern int check_async_event_handlers (); |
1a5c2598 | 113 | |
6b01403b SM |
114 | enum class debug_event_loop_kind |
115 | { | |
116 | OFF, | |
117 | ||
118 | /* Print all event-loop related messages, except events from user-interface | |
119 | event sources. */ | |
120 | ALL_EXCEPT_UI, | |
121 | ||
122 | /* Print all event-loop related messages. */ | |
123 | ALL, | |
124 | }; | |
125 | ||
126 | /* True if we are printing event loop debug statements. */ | |
127 | extern debug_event_loop_kind debug_event_loop; | |
128 | ||
17417fb0 | 129 | /* Print an "event loop" debug statement. */ |
6b01403b SM |
130 | |
131 | #define event_loop_debug_printf(fmt, ...) \ | |
74b773fc SM |
132 | debug_prefixed_printf_cond (debug_event_loop != debug_event_loop_kind::OFF, \ |
133 | "event-loop", fmt, ##__VA_ARGS__) | |
6b01403b | 134 | |
17417fb0 SM |
135 | /* Print an "event loop" debug statement that is know to come from a UI-related |
136 | event (e.g. calling the event handler for the fd of the CLI). */ | |
137 | ||
6b01403b SM |
138 | #define event_loop_ui_debug_printf(is_ui, fmt, ...) \ |
139 | do \ | |
140 | { \ | |
141 | if (debug_event_loop == debug_event_loop_kind::ALL \ | |
142 | || (debug_event_loop == debug_event_loop_kind::ALL_EXCEPT_UI \ | |
143 | && !is_ui)) \ | |
17417fb0 | 144 | debug_prefixed_printf ("event-loop", __func__, fmt, ##__VA_ARGS__); \ |
6b01403b SM |
145 | } \ |
146 | while (0) | |
147 | ||
1a5c2598 | 148 | #endif /* EVENT_LOOP_H */ |