| @@ -1,129 +1,131 @@ | | | @@ -1,129 +1,131 @@ |
1 | /* Definitions used by the GDB event loop. | | 1 | /* Definitions used by the GDB event loop. |
2 | Copyright (C) 1999-2016 Free Software Foundation, Inc. | | 2 | Copyright (C) 1999-2016 Free Software Foundation, Inc. |
3 | Written by Elena Zannoni <ezannoni@cygnus.com> of Cygnus Solutions. | | 3 | Written by Elena Zannoni <ezannoni@cygnus.com> of Cygnus Solutions. |
4 | | | 4 | |
5 | This file is part of GDB. | | 5 | This file is part of GDB. |
6 | | | 6 | |
7 | This program is free software; you can redistribute it and/or modify | | 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 | | 8 | it under the terms of the GNU General Public License as published by |
9 | the Free Software Foundation; either version 3 of the License, or | | 9 | the Free Software Foundation; either version 3 of the License, or |
10 | (at your option) any later version. | | 10 | (at your option) any later version. |
11 | | | 11 | |
12 | This program is distributed in the hope that it will be useful, | | 12 | This program is distributed in the hope that it will be useful, |
13 | but WITHOUT ANY WARRANTY; without even the implied warranty of | | 13 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
14 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | | 14 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
15 | GNU General Public License for more details. | | 15 | GNU General Public License for more details. |
16 | | | 16 | |
17 | You should have received a copy of the GNU General Public License | | 17 | You should have received a copy of the GNU General Public License |
18 | along with this program. If not, see <http://www.gnu.org/licenses/>. */ | | 18 | along with this program. If not, see <http://www.gnu.org/licenses/>. */ |
19 | | | 19 | |
20 | /* An event loop listens for events from multiple event sources. When | | 20 | /* An event loop listens for events from multiple event sources. When |
21 | an event arrives, it is queued and processed by calling the | | 21 | an event arrives, it is queued and processed by calling the |
22 | appropriate event handler. The event loop then continues to listen | | 22 | appropriate event handler. The event loop then continues to listen |
23 | for more events. An event loop completes when there are no event | | 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 | | 24 | sources to listen on. External event sources can be plugged into |
25 | the loop. | | 25 | the loop. |
26 | | | 26 | |
27 | There are 4 main components: | | 27 | There are 4 main components: |
28 | - a list of file descriptors to be monitored, GDB_NOTIFIER. | | 28 | - a list of file descriptors to be monitored, GDB_NOTIFIER. |
29 | - a list of asynchronous event sources to be monitored, | | 29 | - a list of asynchronous event sources to be monitored, |
30 | ASYNC_EVENT_HANDLER_LIST. | | 30 | ASYNC_EVENT_HANDLER_LIST. |
31 | - a list of events that have occurred, EVENT_QUEUE. | | 31 | - a list of events that have occurred, EVENT_QUEUE. |
32 | - a list of signal handling functions, SIGHANDLER_LIST. | | 32 | - a list of signal handling functions, SIGHANDLER_LIST. |
33 | | | 33 | |
34 | GDB_NOTIFIER keeps track of the file descriptor based event | | 34 | GDB_NOTIFIER keeps track of the file descriptor based event |
35 | sources. ASYNC_EVENT_HANDLER_LIST keeps track of asynchronous | | 35 | sources. ASYNC_EVENT_HANDLER_LIST keeps track of asynchronous |
36 | event sources that are signalled by some component of gdb, usually | | 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 | | 37 | a target_ops instance. Event sources for gdb are currently the UI |
38 | and the target. Gdb communicates with the command line user | | 38 | and the target. Gdb communicates with the command line user |
39 | interface via the readline library and usually communicates with | | 39 | interface via the readline library and usually communicates with |
40 | remote targets via a serial port. Serial ports are represented in | | 40 | remote targets via a serial port. Serial ports are represented in |
41 | GDB as file descriptors and select/poll calls. For native targets | | 41 | GDB as file descriptors and select/poll calls. For native targets |
42 | instead, the communication varies across operating system debug | | 42 | instead, the communication varies across operating system debug |
43 | APIs, but usually consists of calls to ptrace and waits (via | | 43 | APIs, but usually consists of calls to ptrace and waits (via |
44 | signals) or calls to poll/select (via file descriptors). In the | | 44 | signals) or calls to poll/select (via file descriptors). In the |
45 | current gdb, the code handling events related to the target resides | | 45 | current gdb, the code handling events related to the target resides |
46 | in wait_for_inferior for synchronous targets; or, for asynchronous | | 46 | in wait_for_inferior for synchronous targets; or, for asynchronous |
47 | capable targets, by having the target register either a target | | 47 | capable targets, by having the target register either a target |
48 | controlled file descriptor and/or an asynchronous event source in | | 48 | controlled file descriptor and/or an asynchronous event source in |
49 | the event loop, with the fetch_inferior_event function as the event | | 49 | the event loop, with the fetch_inferior_event function as the event |
50 | callback. In both the synchronous and asynchronous cases, usually | | 50 | callback. In both the synchronous and asynchronous cases, usually |
51 | the target event is collected through the target_wait interface. | | 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 | | 52 | The target is free to install other event sources in the event loop |
53 | if it so requires. | | 53 | if it so requires. |
54 | | | 54 | |
55 | EVENT_QUEUE keeps track of the events that have happened during the | | 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 | | 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 | | 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 | | 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 | | 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. | | 60 | call to poll or select will be made to detect it. |
61 | | | 61 | |
62 | If the events generate signals, they are also queued by special | | 62 | If the events generate signals, they are also queued by special |
63 | functions that are invoked through traditional signal handlers. | | 63 | functions that are invoked through traditional signal handlers. |
64 | The actions to be taken is response to such events will be executed | | 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 | | 65 | when the SIGHANDLER_LIST is scanned, the next time through the |
66 | infinite loop. | | 66 | infinite loop. |
67 | | | 67 | |
68 | Corollary tasks are the creation and deletion of event sources. */ | | 68 | Corollary tasks are the creation and deletion of event sources. */ |
69 | | | 69 | #ifndef _EVENT_LOOP_H_ |
| | | 70 | #define _EVENT_LOOP_H_ |
70 | typedef void *gdb_client_data; | | 71 | typedef void *gdb_client_data; |
71 | struct async_signal_handler; | | 72 | struct async_signal_handler; |
72 | struct async_event_handler; | | 73 | struct async_event_handler; |
73 | typedef void (handler_func) (int, gdb_client_data); | | 74 | typedef void (handler_func) (int, gdb_client_data); |
74 | typedef void (sig_handler_func) (gdb_client_data); | | 75 | typedef void (sig_handler_func) (gdb_client_data); |
75 | typedef void (async_event_handler_func) (gdb_client_data); | | 76 | typedef void (async_event_handler_func) (gdb_client_data); |
76 | typedef void (timer_handler_func) (gdb_client_data); | | 77 | typedef void (timer_handler_func) (gdb_client_data); |
77 | | | 78 | |
78 | /* Exported functions from event-loop.c */ | | 79 | /* Exported functions from event-loop.c */ |
79 | | | 80 | |
80 | extern void start_event_loop (void); | | 81 | extern void start_event_loop (void); |
81 | extern int gdb_do_one_event (void); | | 82 | extern int gdb_do_one_event (void); |
82 | extern void delete_file_handler (int fd); | | 83 | extern void delete_file_handler (int fd); |
83 | extern void add_file_handler (int fd, handler_func *proc, | | 84 | extern void add_file_handler (int fd, handler_func *proc, |
84 | gdb_client_data client_data); | | 85 | gdb_client_data client_data); |
85 | extern struct async_signal_handler * | | 86 | extern struct async_signal_handler * |
86 | create_async_signal_handler (sig_handler_func *proc, | | 87 | create_async_signal_handler (sig_handler_func *proc, |
87 | gdb_client_data client_data); | | 88 | gdb_client_data client_data); |
88 | extern void delete_async_signal_handler (struct async_signal_handler **); | | 89 | extern void delete_async_signal_handler (struct async_signal_handler **); |
89 | extern int create_timer (int milliseconds, | | 90 | extern int create_timer (int milliseconds, |
90 | timer_handler_func *proc, | | 91 | timer_handler_func *proc, |
91 | gdb_client_data client_data); | | 92 | gdb_client_data client_data); |
92 | extern void delete_timer (int id); | | 93 | extern void delete_timer (int id); |
93 | | | 94 | |
94 | /* Call the handler from HANDLER the next time through the event | | 95 | /* Call the handler from HANDLER the next time through the event |
95 | loop. */ | | 96 | loop. */ |
96 | extern void mark_async_signal_handler (struct async_signal_handler *handler); | | 97 | extern void mark_async_signal_handler (struct async_signal_handler *handler); |
97 | | | 98 | |
98 | /* Returns true if HANDLER is marked ready. */ | | 99 | /* Returns true if HANDLER is marked ready. */ |
99 | | | 100 | |
100 | extern int | | 101 | extern int |
101 | async_signal_handler_is_marked (struct async_signal_handler *handler); | | 102 | async_signal_handler_is_marked (struct async_signal_handler *handler); |
102 | | | 103 | |
103 | /* Mark HANDLER as NOT ready. */ | | 104 | /* Mark HANDLER as NOT ready. */ |
104 | | | 105 | |
105 | extern void clear_async_signal_handler (struct async_signal_handler *handler); | | 106 | extern void clear_async_signal_handler (struct async_signal_handler *handler); |
106 | | | 107 | |
107 | /* Create and register an asynchronous event source in the event loop, | | 108 | /* Create and register an asynchronous event source in the event loop, |
108 | and set PROC as its callback. CLIENT_DATA is passed as argument to | | 109 | and set PROC as its callback. CLIENT_DATA is passed as argument to |
109 | PROC upon its invocation. Returns a pointer to an opaque structure | | 110 | PROC upon its invocation. Returns a pointer to an opaque structure |
110 | used to mark as ready and to later delete this event source from | | 111 | used to mark as ready and to later delete this event source from |
111 | the event loop. */ | | 112 | the event loop. */ |
112 | extern struct async_event_handler * | | 113 | extern struct async_event_handler * |
113 | create_async_event_handler (async_event_handler_func *proc, | | 114 | create_async_event_handler (async_event_handler_func *proc, |
114 | gdb_client_data client_data); | | 115 | gdb_client_data client_data); |
115 | | | 116 | |
116 | /* Remove the event source pointed by HANDLER_PTR created by | | 117 | /* Remove the event source pointed by HANDLER_PTR created by |
117 | CREATE_ASYNC_EVENT_HANDLER from the event loop, and release it. */ | | 118 | CREATE_ASYNC_EVENT_HANDLER from the event loop, and release it. */ |
118 | extern void | | 119 | extern void |
119 | delete_async_event_handler (struct async_event_handler **handler_ptr); | | 120 | delete_async_event_handler (struct async_event_handler **handler_ptr); |
120 | | | 121 | |
121 | /* Call the handler from HANDLER the next time through the event | | 122 | /* Call the handler from HANDLER the next time through the event |
122 | loop. */ | | 123 | loop. */ |
123 | extern void mark_async_event_handler (struct async_event_handler *handler); | | 124 | extern void mark_async_event_handler (struct async_event_handler *handler); |
124 | | | 125 | |
125 | /* Mark the handler (ASYNC_HANDLER_PTR) as NOT ready. */ | | 126 | /* Mark the handler (ASYNC_HANDLER_PTR) as NOT ready. */ |
126 | | | 127 | |
127 | extern void clear_async_event_handler (struct async_event_handler *handler); | | 128 | extern void clear_async_event_handler (struct async_event_handler *handler); |
128 | | | 129 | |
129 | extern void initialize_async_signal_handlers (void); | | 130 | extern void initialize_async_signal_handlers (void); |
| | | 131 | #endif |