| 1 | /* Definitions used by the GDB event loop. |
| 2 | Copyright (C) 1999-2013 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 3 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, see <http://www.gnu.org/licenses/>. */ |
| 19 | |
| 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 | |
| 27 | There are 4 main components: |
| 28 | - a list of file descriptors to be monitored, GDB_NOTIFIER. |
| 29 | - a list of asynchronous event sources to be monitored, |
| 30 | ASYNC_EVENT_HANDLER_LIST. |
| 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 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. |
| 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 | |
| 70 | typedef void *gdb_client_data; |
| 71 | struct async_signal_handler; |
| 72 | struct async_event_handler; |
| 73 | typedef void (handler_func) (int, gdb_client_data); |
| 74 | typedef void (sig_handler_func) (gdb_client_data); |
| 75 | typedef void (async_event_handler_func) (gdb_client_data); |
| 76 | typedef void (timer_handler_func) (gdb_client_data); |
| 77 | |
| 78 | /* Exported functions from event-loop.c */ |
| 79 | |
| 80 | extern void initialize_event_loop (void); |
| 81 | extern void start_event_loop (void); |
| 82 | extern int gdb_do_one_event (void); |
| 83 | extern void delete_file_handler (int fd); |
| 84 | extern void add_file_handler (int fd, handler_func *proc, |
| 85 | gdb_client_data client_data); |
| 86 | extern struct async_signal_handler * |
| 87 | create_async_signal_handler (sig_handler_func *proc, |
| 88 | gdb_client_data client_data); |
| 89 | extern void delete_async_signal_handler (struct async_signal_handler **); |
| 90 | extern int create_timer (int milliseconds, |
| 91 | timer_handler_func *proc, |
| 92 | gdb_client_data client_data); |
| 93 | extern void delete_timer (int id); |
| 94 | |
| 95 | /* Call the handler from HANDLER immediately. This function |
| 96 | runs signal handlers when returning to the event loop would be too |
| 97 | slow. Do not call this directly; use gdb_call_async_signal_handler, |
| 98 | below, with IMMEDIATE_P == 1. */ |
| 99 | void call_async_signal_handler (struct async_signal_handler *handler); |
| 100 | |
| 101 | /* Call the handler from HANDLER the next time through the event loop. |
| 102 | Do not call this directly; use gdb_call_async_signal_handler, |
| 103 | below, with IMMEDIATE_P == 0. */ |
| 104 | void mark_async_signal_handler (struct async_signal_handler *handler); |
| 105 | |
| 106 | /* Wrapper for the body of signal handlers. Call this function from |
| 107 | any SIGINT handler which needs to access GDB data structures or |
| 108 | escape via longjmp. If IMMEDIATE_P is set, this triggers either |
| 109 | immediately (for POSIX platforms), or from gdb_select (for |
| 110 | MinGW). If IMMEDIATE_P is clear, the handler will run the next |
| 111 | time we return to the event loop and any current select calls |
| 112 | will be interrupted. */ |
| 113 | |
| 114 | void gdb_call_async_signal_handler (struct async_signal_handler *handler, |
| 115 | int immediate_p); |
| 116 | |
| 117 | /* Create and register an asynchronous event source in the event loop, |
| 118 | and set PROC as its callback. CLIENT_DATA is passed as argument to |
| 119 | PROC upon its invocation. Returns a pointer to an opaque structure |
| 120 | used to mark as ready and to later delete this event source from |
| 121 | the event loop. */ |
| 122 | extern struct async_event_handler * |
| 123 | create_async_event_handler (async_event_handler_func *proc, |
| 124 | gdb_client_data client_data); |
| 125 | |
| 126 | /* Remove the event source pointed by HANDLER_PTR created by |
| 127 | CREATE_ASYNC_EVENT_HANDLER from the event loop, and release it. */ |
| 128 | extern void |
| 129 | delete_async_event_handler (struct async_event_handler **handler_ptr); |
| 130 | |
| 131 | /* Call the handler from HANDLER the next time through the event |
| 132 | loop. */ |
| 133 | extern void mark_async_event_handler (struct async_event_handler *handler); |