aboutsummaryrefslogtreecommitdiffstats
path: root/src/event
diff options
context:
space:
mode:
authorMax Kellermann <max@duempel.org>2013-11-24 19:28:04 +0100
committerMax Kellermann <max@duempel.org>2013-11-24 19:28:04 +0100
commite53a25cbaee50fdf6b9a4a118677709b47bac4cd (patch)
tree5cfa456cb999bfcbf073ed9e5fd18e30972ee6e7 /src/event
parent41e714597360072b9c765a8265272158d9821bc4 (diff)
downloadmpd-e53a25cbaee50fdf6b9a4a118677709b47bac4cd.tar.gz
mpd-e53a25cbaee50fdf6b9a4a118677709b47bac4cd.tar.xz
mpd-e53a25cbaee50fdf6b9a4a118677709b47bac4cd.zip
event: add API documentation
Diffstat (limited to 'src/event')
-rw-r--r--src/event/Loop.hxx21
-rw-r--r--src/event/MultiSocketMonitor.hxx5
-rw-r--r--src/event/ServerSocket.hxx3
-rw-r--r--src/event/SocketMonitor.hxx6
-rw-r--r--src/event/TimeoutMonitor.hxx4
5 files changed, 38 insertions, 1 deletions
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;