Add comments to event-loop.c

1 files changed, 179 insertions, 0 deletions

diff --git a/event-loop.c b/event-loop.c
index 98009f6..99e19f1 100644
--- a/event-loop.c
+++ b/event-loop.c
@@ -36,22 +36,52 @@
 #include "wayland.h"
 #include "wayland-util.h"
 
+/**
+ * An event loop. Contains the internal state of a standard single-thread
+ * looping daemon.
+ *
+ * epoll_fd: Epoll file descriptor used to wait for new work to come in.
+ * idle_list: List of tasks that should be dispatched as soon as the loop
+ * 	becomes idle.
+ **/
 struct wl_event_loop {
 	int epoll_fd;
 	struct wl_list idle_list;
 };
 
+/**
+ * Set of standard methods for operating on a wl_event_source.
+ *
+ * dispatch: Function to dispatch the given event source.
+ * remove: Function called when given event source is removed from the loop.
+ **/
 struct wl_event_source_interface {
 	void (*dispatch)(struct wl_event_source *source,
 			 struct epoll_event *ep);
 	int (*remove)(struct wl_event_source *source);
 };
 
+/**
+ * A source of events to be handled within the Wayland event loop.
+ *
+ * This struct is polymorphic, so other structs may use it as a base.
+ *
+ * interface: Methods for handling this particular type of event.
+ * loop: The event loop this source belongs to.
+ **/
 struct wl_event_source {
 	struct wl_event_source_interface *interface;
 	struct wl_event_loop *loop;
 };
 
+/**
+ * A wl_event_source for file descriptor event sources.
+ *
+ * base: The base wl_event_source
+ * fd: File descriptor that generates events.
+ * func: Higher-level dispatching function specific to file descriptors.
+ * data: Misc. data passed to `func`.
+ **/
 struct wl_event_source_fd {
 	struct wl_event_source base;
 	int fd;
@@ -59,6 +89,12 @@ struct wl_event_source_fd {
 	void *data;
 };
 
+/**
+ * Dispatch method for wl_event_source_fd type wl_event_sources.
+ *
+ * source: Event source being dispatched.
+ * epoll_event: Event from epoll causing the dispatch.
+ **/
 static void
 wl_event_source_fd_dispatch(struct wl_event_source *source,
 			    struct epoll_event *ep)
@@ -75,6 +111,11 @@ wl_event_source_fd_dispatch(struct wl_event_source *source,
 	fd_source->func(fd_source->fd, mask, fd_source->data);
 }
 
+/**
+ * Remove method for wl_event_source_fd type wl_event_sources.
+ *
+ * source: Event source being dispatched.
+ **/
 static int
 wl_event_source_fd_remove(struct wl_event_source *source)
 {
@@ -89,11 +130,24 @@ wl_event_source_fd_remove(struct wl_event_source *source)
 	return epoll_ctl(loop->epoll_fd, EPOLL_CTL_DEL, fd, NULL);
 }
 
+/**
+ * Interface for wl_event_source_fd type wl_event_sources.
+ **/
 struct wl_event_source_interface fd_source_interface = {
 	wl_event_source_fd_dispatch,
 	wl_event_source_fd_remove
 };
 
+/**
+ * Add a file descriptor to an event loop as an event source.
+ *
+ * loop: Loop to add to.
+ * fd: File descriptor to add.
+ * mask: Bitfield taken from WL_EVENT_READABLE and WL_EVENT_WRITEABLE.
+ * 	Indicates types of states to watch `fd` for.
+ * func: Handler function called when an event occurs.
+ * data: Misc. data passed to `func`.
+ **/
 WL_EXPORT struct wl_event_source *
 wl_event_loop_add_fd(struct wl_event_loop *loop,
 		     int fd, uint32_t mask,
@@ -128,6 +182,13 @@ wl_event_loop_add_fd(struct wl_event_loop *loop,
 	return &source->base;
 }
 
+/**
+ * Change what events a file descriptor event source is listening for.
+ *
+ * source: Source to alter.
+ * mask: ORing of WL_EVENT_READABLE and WL_EVENT_WRITEABLE to indicate whether
+ * 	readability or writeability should be listened for.
+ **/
 WL_EXPORT int
 wl_event_source_fd_update(struct wl_event_source *source, uint32_t mask)
 {
@@ -147,6 +208,14 @@ wl_event_source_fd_update(struct wl_event_source *source, uint32_t mask)
 			 EPOLL_CTL_MOD, fd_source->fd, &ep);
 }
 
+/**
+ * A wl_event_source for timer events.
+ *
+ * base: The base wl_event_source.
+ * fd: Timer file descriptor.
+ * func: Higher-level dispatch function for timer events.
+ * data: Misc. data passed to `func`.
+ **/
 struct wl_event_source_timer {
 	struct wl_event_source base;
 	int fd;
@@ -154,6 +223,12 @@ struct wl_event_source_timer {
 	void *data;
 };
 
+/**
+ * Dispatch method for timer event sources.
+ *
+ * source: The timer event source to dispatch.
+ * ep: Epoll event for the timer file descriptor.
+ **/
 static void
 wl_event_source_timer_dispatch(struct wl_event_source *source,
 			       struct epoll_event *ep)
@@ -167,6 +242,11 @@ wl_event_source_timer_dispatch(struct wl_event_source *source,
 	timer_source->func(timer_source->data);
 }
 
+/**
+ * Remove method for timer event sources.
+ *
+ * source: The timer event source to remove.
+ **/
 static int
 wl_event_source_timer_remove(struct wl_event_source *source)
 {
@@ -181,11 +261,21 @@ wl_event_source_timer_remove(struct wl_event_source *source)
 	return epoll_ctl(loop->epoll_fd, EPOLL_CTL_DEL, fd, NULL);
 }
 
+/**
+ * Interface for wl_event_source_timers
+ **/
 struct wl_event_source_interface timer_source_interface = {
 	wl_event_source_timer_dispatch,
 	wl_event_source_timer_remove
 };
 
+/**
+ * Add a timer to an event loop as an event source.
+ *
+ * loop: Loop to add timer to.
+ * func: Dispatch method to call when the timer fires.
+ * data: Misc. data passed to `func`.
+ **/
 WL_EXPORT struct wl_event_source *
 wl_event_loop_add_timer(struct wl_event_loop *loop,
 			wl_event_loop_timer_func_t func,
@@ -222,6 +312,12 @@ wl_event_loop_add_timer(struct wl_event_loop *loop,
 	return &source->base;
 }
 
+/**
+ * Update the expiration time of a timer event source.
+ *
+ * source: Timer event source to update.
+ * ms_delay: Delay in miliseconds between fires.
+ **/
 WL_EXPORT int
 wl_event_source_timer_update(struct wl_event_source *source, int ms_delay)
 {
@@ -241,6 +337,15 @@ wl_event_source_timer_update(struct wl_event_source *source, int ms_delay)
 	return 0;
 }
 
+/**
+ * A wl_event_source for *nix signals.
+ *
+ * base: The base wl_event_source.
+ * fd: Signalfd file descriptor.
+ * signal_number: The signal number to watch for.
+ * func: Higher-level dispatch function for signal events.
+ * data: Misc. data passed to `func`.
+ **/
 struct wl_event_source_signal {
 	struct wl_event_source base;
 	int fd;
@@ -249,6 +354,12 @@ struct wl_event_source_signal {
 	void *data;
 };
 
+/**
+ * Dispatch method for signal event sources.
+ *
+ * source: The signal event source to dispatch.
+ * ep: Epoll event for the signalfd file descriptor.
+ **/
 static void
 wl_event_source_signal_dispatch(struct wl_event_source *source,
 			       struct epoll_event *ep)
@@ -262,6 +373,11 @@ wl_event_source_signal_dispatch(struct wl_event_source *source,
 	signal_source->func(signal_source->signal_number, signal_source->data);
 }
 
+/**
+ * Remove method for signal event sources.
+ *
+ * source: The signal event source to remove.
+ **/
 static int
 wl_event_source_signal_remove(struct wl_event_source *source)
 {
@@ -276,11 +392,22 @@ wl_event_source_signal_remove(struct wl_event_source *source)
 	return epoll_ctl(loop->epoll_fd, EPOLL_CTL_DEL, fd, NULL);
 }
 
+/**
+ * Interface for wl_event_source_signals
+ **/
 struct wl_event_source_interface signal_source_interface = {
 	wl_event_source_signal_dispatch,
 	wl_event_source_signal_remove
 };
 
+/**
+ * Make a signal an event source in an  event loop.
+ *
+ * loop: Loop to add to.
+ * signal_number: Signal to use.
+ * func: Dispatch method to call when the signal fires.
+ * data: Misc. data passed to `func`.
+ **/
 WL_EXPORT struct wl_event_source *
 wl_event_loop_add_signal(struct wl_event_loop *loop,
 			int signal_number,
@@ -322,6 +449,15 @@ wl_event_loop_add_signal(struct wl_event_loop *loop,
 	return &source->base;
 }
 
+/**
+ * A wl_event_source that is dispatched as soon as the loop has no more work to
+ * do, and is then destroyed.
+ *
+ * base: The base wl_event_source.
+ * link: Links this source into a list of idle events inside the wl_event_loop.
+ * func: Higher-level dispatch function for signal events.
+ * data: Misc. data passed to `func`.
+ **/
 struct wl_event_source_idle {
 	struct wl_event_source base;
 	struct wl_list link;
@@ -329,6 +465,10 @@ struct wl_event_source_idle {
 	void *data;
 };
 
+/**
+ * Dispatch method for wl_event_source_idle event sources. Currently always
+ * throws an error since the dispatch method is circumvented for idle events.
+ **/
 static void
 wl_event_source_idle_dispatch(struct wl_event_source *source,
 			      struct epoll_event *ep)
@@ -336,6 +476,11 @@ wl_event_source_idle_dispatch(struct wl_event_source *source,
 	assert(0);
 }
 
+/**
+ * Remove an idle event source from its event loop.
+ * 
+ * source: Source to remove.
+ **/
 static int
 wl_event_source_idle_remove(struct wl_event_source *source)
 {
@@ -347,11 +492,22 @@ wl_event_source_idle_remove(struct wl_event_source *source)
 	return 0;
 }
 
+/**
+ * Interface for wl_event_source_idle event sources.
+ **/
 struct wl_event_source_interface idle_source_interface = {
 	wl_event_source_idle_dispatch,
 	wl_event_source_idle_remove
 };
 
+/**
+ * Set up `func` to be called the next time `loop` exhausts its workload and
+ * prepares to sleep.
+ *
+ * loop: Loop to call `func`.
+ * func: Function to be called when `loop` goes idle.
+ * data: Misc. data to pass to `func`.
+ **/
 WL_EXPORT struct wl_event_source *
 wl_event_loop_add_idle(struct wl_event_loop *loop,
 		       wl_event_loop_idle_func_t func,
@@ -373,6 +529,11 @@ wl_event_loop_add_idle(struct wl_event_loop *loop,
 	return &source->base;
 }
 
+/**
+ * Remove an event source from the event loop it is in.
+ *
+ * source: Source to remove.
+ **/
 WL_EXPORT int
 wl_event_source_remove(struct wl_event_source *source)
 {
@@ -381,6 +542,9 @@ wl_event_source_remove(struct wl_event_source *source)
 	return 0;
 }
 
+/**
+ * Create and return a new wl_event_loop.
+ **/
 WL_EXPORT struct wl_event_loop *
 wl_event_loop_create(void)
 {
@@ -400,6 +564,11 @@ wl_event_loop_create(void)
 	return loop;
 }
 
+/**
+ * Destroy a wl_event_loop.
+ *
+ * loop: Loop to destroy.
+ **/
 WL_EXPORT void
 wl_event_loop_destroy(struct wl_event_loop *loop)
 {
@@ -407,6 +576,11 @@ wl_event_loop_destroy(struct wl_event_loop *loop)
 	free(loop);
 }
 
+/**
+ * Dispatch any idle event sources for an event loop.
+ *
+ * loop: Loop to dispatch idles for.
+ **/
 static void
 dispatch_idles(struct wl_event_loop *loop)
 {
@@ -426,6 +600,11 @@ dispatch_idles(struct wl_event_loop *loop)
 	wl_list_init(&loop->idle_list);
 }
 
+/**
+ * Block until `loop` has some pending work, then perform that work.
+ *
+ * loop: Loop to block and dispatch.
+ **/
 WL_EXPORT int
 wl_event_loop_wait(struct wl_event_loop *loop)
 {