From e53a25cbaee50fdf6b9a4a118677709b47bac4cd Mon Sep 17 00:00:00 2001
From: Max Kellermann <max@duempel.org>
Date: Sun, 24 Nov 2013 19:28:04 +0100
Subject: event: add API documentation

---
 src/event/Loop.hxx               | 21 +++++++++++++++++++++
 src/event/MultiSocketMonitor.hxx |  5 ++++-
 src/event/ServerSocket.hxx       |  3 +++
 src/event/SocketMonitor.hxx      |  6 ++++++
 src/event/TimeoutMonitor.hxx     |  4 ++++
 5 files changed, 38 insertions(+), 1 deletion(-)

(limited to 'src')

diff --git a/src/event/Loop.hxx b/src/event/Loop.hxx
index 62e733747..223527853 100644
--- a/src/event/Loop.hxx
+++ b/src/event/Loop.hxx
@@ -45,6 +45,15 @@ class SocketMonitor;
 
 #include <assert.h>
 
+/**
+ * An event loop that polls for events on file/socket descriptors.
+ *
+ * This class is not thread-safe, all methods must be called from the
+ * thread that runs it, except where explicitly documented as
+ * thread-safe.
+ *
+ * @see SocketMonitor, MultiSocketMonitor, TimeoutMonitor, IdleMonitor
+ */
 class EventLoop final
 #ifdef USE_EPOLL
 	: private SocketMonitor
@@ -107,10 +116,18 @@ public:
 	EventLoop(Default dummy=Default());
 	~EventLoop();
 
+	/**
+	 * A caching wrapper for MonotonicClockMS().
+	 */
 	unsigned GetTimeMS() const {
 		return now_ms;
 	}
 
+	/**
+	 * Stop execution of this #EventLoop at the next chance.  This
+	 * method is thread-safe and non-blocking: after returning, it
+	 * is not guaranteed that the EventLoop has really stopped.
+	 */
 	void Break();
 
 	bool AddFD(int _fd, unsigned flags, SocketMonitor &m) {
@@ -138,6 +155,10 @@ public:
 
 	void AddCall(std::function<void()> &&f);
 
+	/**
+	 * The main function of this class.  It will loop until
+	 * Break() gets called.  Can be called only once.
+	 */
 	void Run();
 
 private:
diff --git a/src/event/MultiSocketMonitor.hxx b/src/event/MultiSocketMonitor.hxx
index e2197fc90..7ca666246 100644
--- a/src/event/MultiSocketMonitor.hxx
+++ b/src/event/MultiSocketMonitor.hxx
@@ -47,7 +47,10 @@
 class EventLoop;
 
 /**
- * Monitor multiple sockets.
+ * Similar to #SocketMonitor, but monitors multiple sockets.  To use
+ * it, implement the methods PrepareSockets() and DispatchSockets().
+ * In PrepareSockets(), use UpdateSocketList() and AddSocket().
+ * DispatchSockets() will be called if at least one socket is ready.
  */
 class MultiSocketMonitor
 #ifdef USE_EPOLL
diff --git a/src/event/ServerSocket.hxx b/src/event/ServerSocket.hxx
index facb10371..05e13ff63 100644
--- a/src/event/ServerSocket.hxx
+++ b/src/event/ServerSocket.hxx
@@ -36,6 +36,9 @@ typedef void (*server_socket_callback_t)(int fd,
 
 class OneServerSocket;
 
+/**
+ * A socket that accepts incoming stream connections (e.g. TCP).
+ */
 class ServerSocket {
 	friend class OneServerSocket;
 
diff --git a/src/event/SocketMonitor.hxx b/src/event/SocketMonitor.hxx
index 8df604595..ff2864d63 100644
--- a/src/event/SocketMonitor.hxx
+++ b/src/event/SocketMonitor.hxx
@@ -43,6 +43,12 @@
 
 class EventLoop;
 
+/**
+ * Monitor events on a socket.  Call Schedule() to announce events
+ * you're interested in, or Cancel() to cancel your subscription.  The
+ * #EventLoop will invoke virtual method OnSocketReady() as soon as
+ * any of the subscribed events are ready.
+ */
 class SocketMonitor {
 #ifdef USE_EPOLL
 #else
diff --git a/src/event/TimeoutMonitor.hxx b/src/event/TimeoutMonitor.hxx
index 98e4e5564..aa2bbea39 100644
--- a/src/event/TimeoutMonitor.hxx
+++ b/src/event/TimeoutMonitor.hxx
@@ -28,6 +28,10 @@
 
 class EventLoop;
 
+/**
+ * This class monitors a timeout.  Use Schedule() to begin the timeout
+ * or Cancel() to cancel it.
+ */
 class TimeoutMonitor {
 #ifdef USE_EPOLL
 	friend class EventLoop;
-- 
cgit v1.2.3