* event-loop.h: Mention async_event_handlers.

	(async_event_handler): Forward declare.
	(async_event_handler_func): New typedef.
	(create_async_event_handler, delete_async_event_handler)
	(mark_async_event_handler): Declare.
	* event-loop.c (event_data): New.
	(event_handler_func): Take an event_data instead of an integer.
	(struct gdb_event): Replace the integer file descriptor by a
	generic event_data.
	(async_event_handler): New.
	(async_handler_ready): Delete.
	(async_event_handler_list): New.
	(create_event): New.
	(create_file_event): Use it.
	(process_event): Adjust.
	(gdb_do_one_event): Poll from the event sources in round-robin
	fashion across calls.  Be sure to consult all sources before
	blocking.
	(handle_file_event): Take an event_data instead of an integer.
	Adjust.
	(gdb_wait_for_event): Add `block' argument.  Handle it.
	(mark_async_signal_handler): Remove unneeded cast.
	(invoke_async_signal_handler): Rename to ...
	(invoke_async_signal_handlres): ... this.  Return true if any was
	handled.
	(check_async_ready): Delete
	(create_async_event_handler): New.
	(mark_async_event_handler): New.
	(struct async_event_handler_data): New.
	(invoke_async_event_handler): New.
	(check_async_event_handlers): New.
	(delete_async_event_handler): New.
	(handle_timer_event): Adjust.

1 files changed, 43 insertions, 11 deletions

diff --git a/gdb/event-loop.h b/gdb/event-loop.h
index fc813ca5bf..2a75b81ea3 100644
--- a/gdb/event-loop.h
+++ b/gdb/event-loop.h
@@ -24,21 +24,33 @@
    sources to listen on.  External event sources can be plugged into
    the loop.
 
-   There are 3 main components: 
+   There are 4 main components:
    - a list of file descriptors to be monitored, GDB_NOTIFIER.  
+   - a list of asynchronous event sources to be monitored,
+     ASYNC_EVENT_HANDLER_LIST.
    - a list of events that have occurred, EVENT_QUEUE.  
    - a list of signal handling functions, SIGHANDLER_LIST.
 
-   GDB_NOTIFIER keeps track of the event sources. Event sources for
-   gdb are currently the UI and the target.  Gdb communicates with the
-   command line user interface via the readline library and usually
-   communicates with remote targets via a serial port. Serial ports
-   are represented in GDB as file descriptors and select/poll calls.
-   For native targets instead, the communication consists of calls to
-   ptrace and waits (via signals) or calls to poll/select (via file
-   descriptors). In the current gdb, the code handling events related
-   to the target resides in the wait_for_inferior function and in
-   various target specific files (*-tdep.c).
+   GDB_NOTIFIER keeps track of the file descriptor based event
+   sources.  ASYNC_EVENT_HANDLER_LIST keeps track of asynchronous
+   event sources that are signalled by some component of gdb, usually
+   a target_ops instance.  Event sources for gdb are currently the UI
+   and the target.  Gdb communicates with the command line user
+   interface via the readline library and usually communicates with
+   remote targets via a serial port.  Serial ports are represented in
+   GDB as file descriptors and select/poll calls.  For native targets
+   instead, the communication varies across operating system debug
+   APIs, but usually consists of calls to ptrace and waits (via
+   signals) or calls to poll/select (via file descriptors).  In the
+   current gdb, the code handling events related to the target resides
+   in wait_for_inferior for synchronous targets; or, for asynchronous
+   capable targets, by having the target register either a target
+   controlled file descriptor and/or an asynchronous event source in
+   the event loop, with the fetch_inferior_event function as the event
+   callback.  In both the synchronous and asynchronous cases, usually
+   the target event is collected through the target_wait interface.
+   The target is free to install other event sources in the event loop
+   if it so requires.
 
    EVENT_QUEUE keeps track of the events that have happened during the
    last iteration of the event loop, and need to be processed.  An
@@ -57,8 +69,10 @@
 
 typedef void *gdb_client_data;
 struct async_signal_handler;
+struct async_event_handler;
 typedef void (handler_func) (int, gdb_client_data);
 typedef void (sig_handler_func) (gdb_client_data);
+typedef void (async_event_handler_func) (gdb_client_data);
 typedef void (timer_handler_func) (gdb_client_data);
 
 /* Where to add an event onto the event queue, by queue_event. */
@@ -113,3 +127,21 @@ void mark_async_signal_handler (struct async_signal_handler *handler);
 
 void gdb_call_async_signal_handler (struct async_signal_handler *handler,
 				    int immediate_p);
+
+/* Create and register an asynchronous event source in the event loop,
+   and set PROC as its callback.  CLIENT_DATA is passed as argument to
+   PROC upon its invocation.  Returns a pointer to an opaque structure
+   used to mark as ready and to later delete this event source from
+   the event loop.  */
+extern struct async_event_handler *
+  create_async_event_handler (async_event_handler_func *proc,
+			      gdb_client_data client_data);
+
+/* Remove the event source pointed by HANDLER_PTR created by
+   CREATE_ASYNC_EVENT_HANDLER from the event loop, and release it.  */
+extern void
+  delete_async_event_handler (struct async_event_handler **handler_ptr);
+
+/* Call the handler from HANDLER the next time through the event
+   loop.  */
+extern void mark_async_event_handler (struct async_event_handler *handler);