]> arthur.barton.de Git - ngircd-alex.git/blobdiff - src/ngircd/io.c
add support for the poll() interface
[ngircd-alex.git] / src / ngircd / io.c
index 6b4081c870b792adbdc25deb5b15029deda0af23..9633f6cedf6eeaf7003ad0ee45abc3b1e3eaa395 100644 (file)
@@ -12,7 +12,7 @@
 
 #include "portab.h"
 
-static char UNUSED id[] = "$Id: io.c,v 1.3 2005/07/12 20:44:13 fw Exp $";
+static char UNUSED id[] = "$Id: io.c,v 1.18 2006/09/16 15:00:10 fw Exp $";
 
 #include <assert.h>
 #include <stdlib.h>
@@ -26,10 +26,11 @@ static char UNUSED id[] = "$Id: io.c,v 1.3 2005/07/12 20:44:13 fw Exp $";
 #include "io.h"
 #include "log.h"
 
+/* Enables extra debug messages in event add/delete/callback code. */
+/* #define DEBUG_IO */
 
 typedef struct {
  void (*callback)(int, short);
- int fd;
  short what;
 } io_event;
 
@@ -42,17 +43,21 @@ typedef struct {
 # ifdef HAVE_KQUEUE
 #define IO_USE_KQUEUE   1
 # else
+#   ifdef HAVE_POLL
+#define IO_USE_POLL     1
+#   else
 #define IO_USE_SELECT   1
-#endif
-#endif
+#   endif /* HAVE_POLL */
+# endif /* HAVE_KQUEUE */
+#endif /* HAVE_EPOLL_CREATE */
 
+static bool library_initialized;
 
 #ifdef IO_USE_EPOLL
 #include <sys/epoll.h>
 
 static int io_masterfd;
-static bool io_event_new_epoll(int fd, short what);
-static bool io_event_change_epoll(int fd, short what);
+static bool io_event_change_epoll(int fd, short what, const int action);
 static int io_dispatch_epoll(struct timeval *tv);
 #endif
 
@@ -63,7 +68,15 @@ static array io_evcache;
 static int io_masterfd;
 
 static int io_dispatch_kqueue(struct timeval *tv);
-static bool io_event_add_kqueue(int, short);
+static bool io_event_change_kqueue(int, short, const int action);
+#endif
+
+#ifdef IO_USE_POLL
+#include <poll.h>
+static array pollfds;
+static int poll_maxfd;
+
+static bool io_event_change_poll(int fd, short what);
 #endif
 
 #ifdef IO_USE_SELECT
@@ -86,65 +99,127 @@ static io_event *
 io_event_get(int fd)
 {
        io_event *i;
+
        assert(fd >= 0);
-       i = (io_event *) array_get(&io_events, sizeof(io_event), fd);
-       assert(i);
+
+       i = (io_event *) array_get(&io_events, sizeof(io_event), (size_t) fd);
+
+       assert(i != NULL);
 
        return i;
 }
 
 
-bool
-io_library_init(unsigned int eventsize)
+#ifdef IO_USE_POLL
+static bool
+io_library_init_poll(unsigned int eventsize)
 {
-#ifdef IO_USE_EPOLL
-       int ecreate_hint = (int)eventsize;
-       if (ecreate_hint <= 0)
-               ecreate_hint = 128;
+       struct pollfd *p;
+       array_init(&pollfds);
+       poll_maxfd = 0;
+       Log(LOG_INFO, "IO subsystem: poll (initial maxfd %u).",
+           eventsize);
+       p = array_alloc(&pollfds, sizeof(struct pollfd), eventsize);
+       if (p) {
+               unsigned i;
+               p = array_start(&pollfds);
+               for (i = 0; i < eventsize; i++)
+                       p[i].fd = -1;
+
+               library_initialized = true;
+       }
+       return p != NULL;
+}
 #endif
 
-#ifdef IO_USE_SELECT
-#ifdef FD_SETSIZE
-       if (eventsize >= FD_SETSIZE)
-               eventsize = FD_SETSIZE - 1;
-#endif
-#endif
-       if (eventsize && !array_alloc(&io_events, sizeof(io_event), eventsize))
-               eventsize = 0;
 
-#ifdef IO_USE_EPOLL
-       io_masterfd = epoll_create(ecreate_hint);
-       Log(LOG_INFO,
-           "io subsystem: using epoll (hint size %d), initial io_event maxfd: %u, io_masterfd %d",
-           ecreate_hint, eventsize, io_masterfd);
-       return io_masterfd >= 0;
-#endif
 #ifdef IO_USE_SELECT
-       Log(LOG_INFO, "io subsystem: using select, initial io_event maxfd: %u",
+static bool
+io_library_init_select(unsigned int eventsize)
+{
+       Log(LOG_INFO, "IO subsystem: select (initial maxfd %u).",
            eventsize);
        FD_ZERO(&readers);
        FD_ZERO(&writers);
 #ifdef FD_SETSIZE
-       if (Conf_MaxConnections >= FD_SETSIZE) {
+       if (Conf_MaxConnections >= (int)FD_SETSIZE) {
                Log(LOG_WARNING,
-                   "Conf_MaxConnections (%d) exceeds limit (%u), changed Conf_MaxConnections to %u",
+                   "MaxConnections (%d) exceeds limit (%u), changed MaxConnections to %u.",
                    Conf_MaxConnections, FD_SETSIZE, FD_SETSIZE - 1);
 
                Conf_MaxConnections = FD_SETSIZE - 1;
        }
-#else
-       Log(LOG_WARNING,
-           "FD_SETSIZE undefined, don't know how many descriptors select() can handle on your platform");
-#endif
+#endif /* FD_SETSIZE */
+       library_initialized = true;
        return true;
+}
+#endif /* SELECT */
+
+
+#ifdef IO_USE_EPOLL
+static bool
+io_library_init_epoll(unsigned int eventsize)
+{
+       bool ret;
+       int ecreate_hint = (int)eventsize;
+       if (ecreate_hint <= 0)
+               ecreate_hint = 128;
+       io_masterfd = epoll_create(ecreate_hint);
+       Log(LOG_INFO,
+           "IO subsystem: epoll (hint size %d, initial maxfd %u, masterfd %d).",
+           ecreate_hint, eventsize, io_masterfd);
+       ret = io_masterfd >= 0;
+       if (ret) library_initialized = true;
+
+       return ret;
+}
 #endif
+
+
 #ifdef IO_USE_KQUEUE
+static bool
+io_library_init_kqueue(unsigned int eventsize)
+{
+       bool ret;
        io_masterfd = kqueue();
 
        Log(LOG_INFO,
-           "io subsystem: using kqueue, initial io_event maxfd: %u, io_masterfd %d",
+           "IO subsystem: kqueue (initial maxfd %u, masterfd %d)",
            eventsize, io_masterfd);
-       return io_masterfd >= 0;
+       ret = io_masterfd >= 0;
+       if (ret) library_initialized = true;
+       return ret;
+}
+#endif
+
+
+bool
+io_library_init(unsigned int eventsize)
+{
+       if (library_initialized)
+               return true;
+#ifdef IO_USE_SELECT
+#ifndef FD_SETSIZE
+       Log(LOG_WARNING,
+           "FD_SETSIZE undefined, don't know how many descriptors select() can handle on your platform ...");
+#else
+       if (eventsize >= FD_SETSIZE)
+               eventsize = FD_SETSIZE - 1;
+#endif /* FD_SETSIZE */
+#endif /* IO_USE_SELECT */
+       if ((eventsize > 0) && !array_alloc(&io_events, sizeof(io_event), (size_t)eventsize))
+               eventsize = 0;
+#ifdef IO_USE_EPOLL
+       return io_library_init_epoll(eventsize);
+#endif
+#ifdef IO_USE_KQUEUE
+       return io_library_init_kqueue(eventsize);
+#endif
+#ifdef IO_USE_POLL
+       return io_library_init_poll(eventsize);
+#endif
+#ifdef IO_USE_SELECT
+       return io_library_init_select(eventsize);
 #endif
 }
 
@@ -155,13 +230,17 @@ io_library_shutdown(void)
 #ifdef IO_USE_SELECT
        FD_ZERO(&readers);
        FD_ZERO(&writers);
-#else
-       close(io_masterfd);     /* kqueue, epoll */
+#endif
+#ifdef IO_USE_EPOLL
+       close(io_masterfd);
        io_masterfd = -1;
 #endif
 #ifdef IO_USE_KQUEUE
+       close(io_masterfd);
+       io_masterfd = -1;
        array_free(&io_evcache);
 #endif
+       library_initialized = false;
 }
 
 
@@ -180,22 +259,19 @@ io_event_setcb(int fd, void (*cbfunc) (int, short))
 bool
 io_event_create(int fd, short what, void (*cbfunc) (int, short))
 {
+       bool ret;
        io_event *i;
 
        assert(fd >= 0);
-
-#ifdef IO_USE_SELECT
-#ifdef FD_SETSIZE
+#if defined(IO_USE_SELECT) || defined(FD_SETSIZE)
        if (fd >= FD_SETSIZE) {
                Log(LOG_ERR,
                    "fd %d exceeds FD_SETSIZE (%u) (select can't handle more file descriptors)",
                    fd, FD_SETSIZE);
                return false;
        }
-#endif                         /* FD_SETSIZE */
-#endif                         /* IO_USE_SELECT */
-
-       i = (io_event *) array_alloc(&io_events, sizeof(io_event), fd);
+#endif
+       i = (io_event *) array_alloc(&io_events, sizeof(io_event), (size_t) fd);
        if (!i) {
                Log(LOG_WARNING,
                    "array_alloc failed: could not allocate space for %d io_event structures",
@@ -203,41 +279,51 @@ io_event_create(int fd, short what, void (*cbfunc) (int, short))
                return false;
        }
 
-       i->fd = fd;
        i->callback = cbfunc;
+       i->what = 0;
+#ifdef IO_USE_POLL
+       ret = io_event_change_poll(fd, what);
+#endif
 #ifdef IO_USE_EPOLL
-       i->what = what;
-       return io_event_new_epoll(fd, what);
+       ret = io_event_change_epoll(fd, what, EPOLL_CTL_ADD);
 #endif
 #ifdef IO_USE_KQUEUE
-       i->what = what;
-       return io_event_add_kqueue(fd, what);
+       ret = io_event_change_kqueue(fd, what, EV_ADD|EV_ENABLE);
 #endif
 #ifdef IO_USE_SELECT
-       i->what = 0;
-       return io_event_add(fd, what);
+       ret = io_event_add(fd, what);
 #endif
+       if (ret) i->what = what;
+       return ret;
 }
 
 
-#ifdef IO_USE_EPOLL
+#ifdef IO_USE_POLL
 static bool
-io_event_new_epoll(int fd, short what)
+io_event_change_poll(int fd, short what)
 {
-       struct epoll_event ev = { 0, {0} };
-       ev.data.fd = fd;
+       struct pollfd *p;
+       short events = 0;
 
        if (what & IO_WANTREAD)
-               ev.events = EPOLLIN | EPOLLPRI;
+               events = POLLIN | POLLPRI;
        if (what & IO_WANTWRITE)
-               ev.events |= EPOLLOUT;
-
-       return epoll_ctl(io_masterfd, EPOLL_CTL_ADD, fd, &ev) == 0;
+               events |= POLLOUT;
+
+       p = array_alloc(&pollfds, sizeof *p, fd);
+       if (p) {
+               p->events = events;
+               p->fd = fd;
+               if (fd > poll_maxfd)
+                       poll_maxfd = fd;
+       }
+       return p != NULL;
 }
+#endif
 
-
+#ifdef IO_USE_EPOLL
 static bool
-io_event_change_epoll(int fd, short what)
+io_event_change_epoll(int fd, short what, const int action)
 {
        struct epoll_event ev = { 0, {0} };
        ev.data.fd = fd;
@@ -247,7 +333,7 @@ io_event_change_epoll(int fd, short what)
        if (what & IO_WANTWRITE)
                ev.events |= EPOLLOUT;
 
-       return epoll_ctl(io_masterfd, EPOLL_CTL_MOD, fd, &ev) == 0;
+       return epoll_ctl(io_masterfd, action, fd, &ev) == 0;
 }
 #endif
 
@@ -258,7 +344,7 @@ io_event_kqueue_commit_cache(void)
        struct kevent *events;
        bool ret;
        int len = (int) array_length(&io_evcache, sizeof (struct kevent));
+
        if (!len) /* nothing to do */
                return true;
 
@@ -271,7 +357,7 @@ io_event_kqueue_commit_cache(void)
 
        events = array_start(&io_evcache);
 
-       assert(events);
+       assert(events != NULL);
 
        ret = kevent(io_masterfd, events, len, NULL, 0, NULL) == 0;
        if (ret)
@@ -281,27 +367,28 @@ io_event_kqueue_commit_cache(void)
 
 
 static bool
-io_event_add_kqueue(int fd, short what)
+io_event_change_kqueue(int fd, short what, const int action)
 {
        struct kevent kev;
-       short filter = 0;
-       unsigned int len = array_length(&io_evcache, sizeof kev);
-       bool ret;
+       bool ret = true;
 
-       if (what & IO_WANTREAD)
-               filter = EVFILT_READ;
-
-       if (what & IO_WANTWRITE)
-               filter |= EVFILT_WRITE;
+       if (what & IO_WANTREAD) {
+               EV_SET(&kev, fd, EVFILT_READ, action, 0, 0, 0);
+               ret = array_catb(&io_evcache, (char*) &kev, sizeof (kev));
+               if (!ret)
+                       ret = kevent(io_masterfd, &kev,1, NULL, 0, NULL) == 0;
+       }
 
-       if (len >= 100) {
-               ret = io_event_kqueue_commit_cache();
-               if (ret)
-                       array_trunc(&io_evcache);
+       if (ret && (what & IO_WANTWRITE)) {
+               EV_SET(&kev, fd, EVFILT_WRITE, action, 0, 0, 0);
+               ret = array_catb(&io_evcache, (char*) &kev, sizeof (kev));
+               if (!ret)
+                       ret = kevent(io_masterfd, &kev, 1, NULL, 0, NULL) == 0;
        }
 
-       EV_SET(&kev, fd, filter, EV_ADD | EV_ENABLE, 0, 0, NULL);
-       return array_catb(&io_evcache, (char*) &kev, sizeof (kev));
+       if (array_length(&io_evcache, sizeof kev) >= 100)
+               io_event_kqueue_commit_cache();
+       return ret;
 }
 #endif
 
@@ -311,26 +398,22 @@ io_event_add(int fd, short what)
 {
        io_event *i = io_event_get(fd);
 
-       assert(i);
-
-       if (!i)
-               return false;
-       if (i->what == what)
-               return true;
-#ifdef DEBUG
+       if (!i) return false;
+       if (i->what == what) return true;
+#ifdef DEBUG_IO
        Log(LOG_DEBUG, "io_event_add(): fd %d (arg: %d), what %d.", i->fd, fd, what);
 #endif
-
        i->what |= what;
-
 #ifdef IO_USE_EPOLL
-       return io_event_change_epoll(fd, i->what);
+       return io_event_change_epoll(fd, i->what, EPOLL_CTL_MOD);
 #endif
 
 #ifdef IO_USE_KQUEUE
-       return io_event_add_kqueue(fd, what);
+       return io_event_change_kqueue(fd, what, EV_ADD | EV_ENABLE);
+#endif
+#ifdef IO_USE_POLL
+       return io_event_change_poll(fd, i->what);
 #endif
-
 #ifdef IO_USE_SELECT
        if (fd > select_maxfd)
                select_maxfd = fd;
@@ -361,67 +444,113 @@ io_setnonblock(int fd)
 }
 
 
-bool
-io_close(int fd)
+#ifdef IO_USE_POLL
+static void
+io_close_poll(int fd)
 {
-       io_event *i = io_event_get(fd);
-       if (i) {
-               memset(i, 0, sizeof(io_event));
-               i->fd = -1;
+       struct pollfd *p;
+       p = array_get(&pollfds, sizeof *p, fd);
+       if (!p) return;
+
+       p->fd = -1;
+       if (fd == poll_maxfd) {
+               while (poll_maxfd > 0) {
+                       --poll_maxfd;
+                       p = array_get(&pollfds, sizeof *p, poll_maxfd);
+                       if (p && p->fd >= 0)
+                               break;
+               }
        }
+}
+#else
+static inline void io_close_poll(int UNUSED x) { /* NOTHING */ }
+#endif
+
+
 #ifdef IO_USE_SELECT
+static void
+io_close_select(int fd)
+{
+       io_event *i;
        FD_CLR(fd, &writers);
        FD_CLR(fd, &readers);
 
-       if (fd == select_maxfd)
-               select_maxfd--;
+       i = io_event_get(fd);
+       if (!i) return;
+
+       if (fd == select_maxfd) {
+               while (select_maxfd>0) {
+                       --select_maxfd; /* find largest fd */
+                       i = io_event_get(select_maxfd);
+                       if (i && i->callback) break;
+               }
+       }
+}
+#else
+static inline void io_close_select(int UNUSED x) { /* NOTHING */ }
 #endif
+
+
+bool
+io_close(int fd)
+{
+       io_event *i;
+
+       i = io_event_get(fd);
 #ifdef IO_USE_KQUEUE
        if (array_length(&io_evcache, sizeof (struct kevent)))  /* pending data in cache? */
                io_event_kqueue_commit_cache();
+
+       /* both kqueue and epoll remove fd from all sets automatically on the last close
+        * of the descriptor. since we don't know if this is the last close we'll have
+        * to remove the set explicitly. */
+       if (i) {
+               io_event_change_kqueue(fd, i->what, EV_DELETE);
+               io_event_kqueue_commit_cache();
+       }
 #endif
-       return close(fd) == 0;  /* both epoll an kqueue will remove fd from all sets automatically */
+
+       io_close_poll(fd);
+       io_close_select(fd);
+
+#ifdef IO_USE_EPOLL
+       io_event_change_epoll(fd, 0, EPOLL_CTL_DEL);
+#endif
+       if (i) {
+               i->callback = NULL;
+               i->what = 0;
+       }
+       return close(fd) == 0;
 }
 
 
 bool
 io_event_del(int fd, short what)
 {
-#ifdef IO_USE_KQUEUE
-       struct kevent kev;
-       short filter = 0;
-#endif
        io_event *i = io_event_get(fd);
-#ifdef DEBUG
+#ifdef DEBUG_IO
        Log(LOG_DEBUG, "io_event_del(): trying to delete eventtype %d on fd %d", what, fd);
 #endif
-       assert(i);
-       if (!i)
-               return false;
+       if (!i) return false;
 
        i->what &= ~what;
 
+#ifdef IO_USE_POLL
+       return io_event_change_poll(fd, i->what);
+#endif
 #ifdef IO_USE_EPOLL
-       return io_event_change_epoll(fd, i->what);
+       return io_event_change_epoll(fd, i->what, EPOLL_CTL_MOD);
 #endif
 
 #ifdef IO_USE_KQUEUE
-       if (what & IO_WANTREAD)
-               filter = EVFILT_READ;
-
-       if (what & IO_WANTWRITE)
-               filter |= EVFILT_WRITE;
-
-       EV_SET(&kev, fd, filter, EV_DELETE, 0, 0, NULL);
-       return kevent(io_masterfd, &kev, 1, NULL, 0, NULL) == 0;
+       return io_event_change_kqueue(fd, what, EV_DISABLE);
 #endif
-
 #ifdef IO_USE_SELECT
        if (what & IO_WANTWRITE)
-               FD_CLR(i->fd, &writers);
+               FD_CLR(fd, &writers);
 
        if (what & IO_WANTREAD)
-               FD_CLR(i->fd, &readers);
+               FD_CLR(fd, &readers);
 
        return true;
 #endif
@@ -465,6 +594,49 @@ io_dispatch_select(struct timeval *tv)
 #endif
 
 
+#ifdef IO_USE_POLL
+static int
+io_dispatch_poll(struct timeval *tv)
+{
+       time_t sec = tv->tv_sec * 1000;
+       int i, ret, timeout = tv->tv_usec + sec;
+       int fds_ready;
+       short what;
+       struct pollfd *p = array_start(&pollfds);
+
+       if (timeout < 0)
+               timeout = 1000;
+
+       ret = poll(p, poll_maxfd + 1, timeout);
+       if (ret <= 0)
+               return ret;
+
+       fds_ready = ret;
+       for (i=0; i <= poll_maxfd; i++) {
+               what = 0;
+               if (p[i].revents & (POLLIN|POLLPRI))
+                       what = IO_WANTREAD;
+
+               if (p[i].revents & POLLOUT)
+                       what |= IO_WANTWRITE;
+
+               if (p[i].revents && !what) {
+                       /* other flag is set, probably POLLERR */
+                       what = IO_ERROR;
+               }
+               if (what) {
+                       fds_ready--;
+                       io_docallback(i, what);
+               }
+               if (fds_ready <= 0)
+                       break;
+       }
+
+       return ret;
+}
+#endif
+
+
 #ifdef IO_USE_EPOLL
 static int
 io_dispatch_epoll(struct timeval *tv)
@@ -511,25 +683,24 @@ io_dispatch_kqueue(struct timeval *tv)
 {
        int i, total = 0, ret;
        struct kevent kev[100];
-       struct kevents *newevents;
+       struct kevent *newevents;
        struct timespec ts;
        int newevents_len;
-       short type;
        ts.tv_sec = tv->tv_sec;
        ts.tv_nsec = tv->tv_usec * 1000;
-       
+
        do {
-               newevents_len = array_length(&io_evcache, sizeof (struct kevent));
+               newevents_len = (int) array_length(&io_evcache, sizeof (struct kevent));
                newevents = (newevents_len > 0) ? array_start(&io_evcache) : NULL;
                assert(newevents_len >= 0);
                if (newevents_len < 0)
                        newevents_len = 0;
 #ifdef DEBUG
                if (newevents_len)
-                       assert(newevents);
+                       assert(newevents != NULL);
 #endif
-
-               ret = kevent(io_masterfd, newevents, newevents_len, kev, 100, &ts);
+               ret = kevent(io_masterfd, newevents, newevents_len, kev,
+                            100, &ts);
                if ((newevents_len>0) && ret != -1)
                        array_trunc(&io_evcache);
 
@@ -538,25 +709,34 @@ io_dispatch_kqueue(struct timeval *tv)
                        return total;
 
                for (i = 0; i < ret; i++) {
-                       type = 0;
-                       if (kev[i].flags & EV_EOF)
-                               type = IO_ERROR;
-
-                       if (kev[i].filter & EV_ERROR)
-                               type = IO_ERROR;
-
-                       if (kev[i].filter & EVFILT_READ)
-                               type |= IO_WANTREAD;
-
-                       if (kev[i].filter & EVFILT_WRITE)
-                               type |= IO_WANTWRITE;
-
-                       io_docallback(kev[i].ident, type);
+                       if (kev[i].flags & EV_EOF) {
+#ifdef DEBUG
+                               LogDebug("kev.flag has EV_EOF set, setting IO_ERROR",
+                                       kev[i].filter, kev[i].ident);
+#endif
+                               io_docallback((int)kev[i].ident, IO_ERROR);
+                               continue;
+                       }
+
+                       switch (kev[i].filter) {
+                               case EVFILT_READ:
+                                       io_docallback((int)kev[i].ident, IO_WANTREAD);
+                                       break;
+                               case EVFILT_WRITE:
+                                       io_docallback((int)kev[i].ident, IO_WANTWRITE);
+                                       break;
+                               default:
+#ifdef DEBUG
+                                       LogDebug("Unknown kev.filter number %d for fd %d",
+                                               kev[i].filter, kev[i].ident); /* Fall through */
+#endif
+                               case EV_ERROR:
+                                       io_docallback((int)kev[i].ident, IO_ERROR);
+                                       break;
+                       }
                }
-
                ts.tv_sec = 0;
                ts.tv_nsec = 0;
-
        } while (ret == 100);
 
        return total;
@@ -573,6 +753,9 @@ io_dispatch(struct timeval *tv)
 #ifdef IO_USE_KQUEUE
        return io_dispatch_kqueue(tv);
 #endif
+#ifdef IO_USE_POLL
+       return io_dispatch_poll(tv);
+#endif
 #ifdef IO_USE_EPOLL
        return io_dispatch_epoll(tv);
 #endif
@@ -584,13 +767,14 @@ static void
 io_docallback(int fd, short what)
 {
        io_event *i;
-#ifdef DEBUG
+#ifdef DEBUG_IO
        Log(LOG_DEBUG, "doing callback for fd %d, what %d", fd, what);
 #endif
        i = io_event_get(fd);
-       assert(i);
 
-       if (i->callback)        /* callback might be 0 if previous callback function called io_close on this fd */
+       if (i->callback) {      /* callback might be NULL if a previous callback function
+                                  called io_close on this fd */
                i->callback(fd, (what & IO_ERROR) ? i->what : what);
-       /* if error indicator is set, we return the event(s) the app asked for */
+       }
+       /* if error indicator is set, we return the event(s) that were registered */
 }