iodine 0.4.19 → 0.5.0

data/ext/iodine/defer.h

@@ -23,7 +23,7 @@ call `defer_clear_queue` before exiting the program.
 #define LIB_DEFER_VERSION_MINOR 1
 #define LIB_DEFER_VERSION_PATCH 2
 
-/* child process reaping is enabled by default */
+/* child process reaping is can be enabled as a default */
 #ifndef NO_CHILD_REAPER
 #define NO_CHILD_REAPER 0
 #endif
@@ -54,79 +54,87 @@ Thread Pool support
 /** an opaque thread pool type */
 typedef struct defer_pool *pool_pt;
 
-/** Starts a thread pool that will run deferred tasks in the background. */
+/**
+ * Starts a thread pool that will run deferred tasks in the background.
+ *
+ * The `defer_idle` callback will be used to handle waiting threads. It can be
+ * used to sleep, or run background tasks. It will run concurrently and
+ * continuesly for all the threads in the pool that are idling.
+ *
+ * If `defer_idle` is NULL, a fallback to `nanosleep` will be used.
+ */
 pool_pt defer_pool_start(unsigned int thread_count);
+
 /** Signals a running thread pool to stop. Returns immediately. */
 void defer_pool_stop(pool_pt pool);
-/** Waits for a running thread pool, joining threads and finishing all tasks. */
+
+/**
+ * Waits for a running thread pool, joining threads and finishing all tasks.
+ *
+ * This function MUST be called in order to free the pool's data (the
+ * `pool_pt`).
+ */
 void defer_pool_wait(pool_pt pool);
+
 /** Returns TRUE (1) if the pool is hadn't been signaled to finish up. */
 int defer_pool_is_active(pool_pt pool);
 
 /**
-OVERRIDE THIS to replace the default pthread implementation.
-
-Accepts a pointer to a function and a single argument that should be executed
-within a new thread.
-
-The function should allocate memory for the thread object and return a pointer
-to the allocated memory that identifies the thread.
-
-On error NULL should be returned.
-*/
-void *defer_new_thread(void *(*thread_func)(void *), pool_pt pool);
+ * OVERRIDE THIS to replace the default pthread implementation.
+ *
+ * Accepts a pointer to a function and a single argument that should be executed
+ * within a new thread.
+ *
+ * The function should allocate memory for the thread object and return a
+ * pointer to the allocated memory that identifies the thread.
+ *
+ * On error NULL should be returned.
+ */
+void *defer_new_thread(void *(*thread_func)(void *), void *arg);
 
 /**
-OVERRIDE THIS to replace the default pthread implementation.
-
-Accepts a pointer returned from `defer_new_thread` (should also free any
-allocated memory) and joins the associated thread.
+ * OVERRIDE THIS to replace the default pthread implementation.
+ *
+ * Frees the memory asociated with a thread indentifier (allows the thread to
+ * run it's course, just the identifier is freed).
+ */
+void defer_free_thread(void *p_thr);
 
-Return value is ignored.
-*/
+/**
+ * OVERRIDE THIS to replace the default pthread implementation.
+ *
+ * Accepts a pointer returned from `defer_new_thread` (should also free any
+ * allocated memory) and joins the associated thread.
+ *
+ * Return value is ignored.
+ */
 int defer_join_thread(void *p_thr);
 
 /**
-OVERRIDE THIS to replace the default pthread implementation.
-
-Throttles or reschedules the current running thread. Default implementation
-simply micro-sleeps.
-*/
+ * OVERRIDE THIS to replace the default pthread implementation.
+ *
+ * Throttles or reschedules the current running thread. Default implementation
+ * simply micro-sleeps.
+ */
 void defer_thread_throttle(unsigned long microsec);
 
-/* *****************************************************************************
-Child Process support (`fork`)
-***************************************************************************** */
-
 /**
-OVERRIDE THIS to replace the default `fork` implementation or to inject hooks
-into the forking function.
-
-Behaves like the system's `fork`.
-*/
-int defer_new_child(void);
+ * OVERRIDE THIS to replace the default nanosleep implementation.
+ *
+ * A thread entering this function should wait for new evennts.
+ */
+void defer_thread_wait(pool_pt pool, void *p_thr);
 
 /**
- * Forks the process, starts up a thread pool and waits for all tasks to run.
- * All existing tasks will run in all processes (multiple times).
- *
- * It's possible to synchronize workload across processes by using a pipe (or
- * pipes) and a self-scheduling event that reads instructions from the pipe.
+ * OVERRIDE THIS to replace the default implementation (which does nothing).
  *
- * This function will use SIGINT or SIGTERM to signal all the children processes
- * to finish up and exit. It will also setup a child process reaper (which will
- * remain active for the application's lifetime).
- *
- * Returns 0 on success, -1 on error and a positive number if this is a child
- * process that was forked.
+ * This should signal a single waiting thread to wake up (a new task entered the
+ * queue).
  */
-int defer_perform_in_fork(unsigned int process_count,
-                          unsigned int thread_count);
-/** Returns TRUE (1) if the forked thread pool hadn't been signaled to finish
- * up. */
-int defer_fork_is_active(void);
-/** Returns the process number for the current working proceess. 0 == parent. */
-int defer_fork_pid(void);
+void defer_thread_signal(void);
+
+/** Call this function after forking, to make sure no locks are engaged. */
+void defer_on_fork(void);
 
 #ifdef DEBUG
 /** minor testing facilities */

data/ext/iodine/evio.c

@@ -10,33 +10,8 @@ Feel free to copy, use and enjoy according to the license provided.
 
 #include "evio.h"
 
-#if !defined(__unix__) && !defined(__linux__) && !defined(__APPLE__) &&        \
-    !defined(__CYGWIN__)
-#error This library currently supports only Unix based systems (i.e. Linux and BSD)
-#endif
-
-#include <assert.h>
-#include <errno.h>
-#include <fcntl.h>
-#include <netdb.h>
-#include <stdint.h>
 #include <stdio.h>
 #include <stdlib.h>
-#include <string.h>
-#include <sys/socket.h>
-#include <sys/time.h>
-#include <sys/types.h>
-#include <time.h>
-#include <unistd.h>
-
-/*
-#define EVIO_MAX_EVENTS 64
-#define EVIO_TICK 256
-*/
-
-#if (EVIO_MAX_EVENTS & 1) || EVIO_MAX_EVENTS < 3
-#error EVIO_MAX_EVENTS must be an even number higher than 4
-#endif
 
 /* *****************************************************************************
 Callbacks - weak versions to be overridden.
@@ -49,238 +24,3 @@ void __attribute__((weak)) evio_on_ready(void *arg) { (void)arg; }
 void __attribute__((weak)) evio_on_error(void *arg) { (void)arg; }
 #pragma weak evio_on_close
 void __attribute__((weak)) evio_on_close(void *arg) { (void)arg; }
-
-/* *****************************************************************************
-Global data and system independant code
-***************************************************************************** */
-
-static int evio_fd = -1;
-
-/** Closes the `epoll` / `kqueue` object, releasing it's resources. */
-void evio_close() {
-  if (evio_fd != -1)
-    close(evio_fd);
-  evio_fd = -1;
-}
-
-/**
-returns true if the evio is available for adding or removing file descriptors.
-*/
-int evio_isactive(void) { return evio_fd >= 0; }
-
-#if defined(__linux__) || defined(__CYGWIN__)
-/* *****************************************************************************
-Linux `epoll` implementation
-***************************************************************************** */
-#include <sys/epoll.h>
-#include <sys/timerfd.h>
-
-/**
-Creates the `epoll` or `kqueue` object.
-*/
-intptr_t evio_create() { return evio_fd = epoll_create1(EPOLL_CLOEXEC); }
-
-/**
-Removes a file descriptor from the polling object.
-*/
-int evio_remove(int fd) {
-  struct epoll_event chevent = {0};
-  return epoll_ctl(evio_fd, EPOLL_CTL_DEL, fd, &chevent);
-}
-
-/**
-Adds a file descriptor to the polling object.
-*/
-int evio_add(int fd, void *callback_arg) {
-  struct epoll_event chevent = {0};
-  chevent.data.ptr = (void *)callback_arg;
-  chevent.events = EPOLLOUT | EPOLLIN | EPOLLET | EPOLLRDHUP | EPOLLHUP;
-  return epoll_ctl(evio_fd, EPOLL_CTL_ADD, fd, &chevent);
-}
-
-/**
-Creates a timer file descriptor, system dependent.
-*/
-intptr_t evio_open_timer(void) {
-#ifndef TFD_NONBLOCK
-  intptr_t fd = timerfd_create(CLOCK_MONOTONIC, O_NONBLOCK);
-  if (fd != -1) { /* make sure it's a non-blocking timer. */
-#if defined(O_NONBLOCK)
-    /* Fixme: O_NONBLOCK is defined but broken on SunOS 4.1.x and AIX 3.2.5. */
-    int flags;
-    if (-1 == (flags = fcntl(fd, F_GETFL, 0)))
-      flags = 0;
-    if (fcntl(fd, F_SETFL, flags | O_NONBLOCK) == -1)
-      goto error;
-#else
-    /* no O_NONBLOCK, use the old way of doing it */
-    static int flags = 1;
-    if (ioctl(fd, FIOBIO, &flags) == -1)
-      goto error;
-#endif
-  }
-  return fd;
-error:
-  close(fd);
-  return -1;
-#else
-  return timerfd_create(CLOCK_MONOTONIC, TFD_NONBLOCK);
-#endif
-}
-
-/**
-Adds a timer file descriptor, so that callbacks will be called for it's events.
-*/
-intptr_t evio_add_timer(int fd, void *callback_arg,
-                        unsigned long milliseconds) {
-  struct epoll_event chevent = {.data.ptr = (void *)callback_arg,
-                                .events = (EPOLLIN | EPOLLET)};
-  struct itimerspec new_t_data;
-  new_t_data.it_value.tv_sec = new_t_data.it_interval.tv_sec =
-      milliseconds / 1000;
-  new_t_data.it_value.tv_nsec = new_t_data.it_interval.tv_nsec =
-      (milliseconds % 1000) * 1000000;
-  if (timerfd_settime(fd, 0, &new_t_data, NULL) == -1)
-    return -1;
-  int ret = epoll_ctl(evio_fd, EPOLL_CTL_ADD, fd, &chevent);
-  if (ret == -1 && errno == EEXIST)
-    return 0;
-  return ret;
-}
-
-/** Rearms the timer. Required only by `epoll`.*/
-void evio_reset_timer(int timer_fd) {
-  char data[8]; // void * is 8 byte long
-  if (read(timer_fd, &data, 8) < 0)
-    data[0] = 0;
-}
-
-/**
-Reviews any pending events (up to EVIO_MAX_EVENTS) and calls any callbacks.
- */
-int evio_review(const int timeout_millisec) {
-  if (evio_fd < 0)
-    return -1;
-  struct epoll_event events[EVIO_MAX_EVENTS];
-  /* wait for events and handle them */
-  int active_count =
-      epoll_wait(evio_fd, events, EVIO_MAX_EVENTS, timeout_millisec);
-
-  if (active_count > 0) {
-    for (int i = 0; i < active_count; i++) {
-      if (events[i].events & (~(EPOLLIN | EPOLLOUT))) {
-        // errors are hendled as disconnections (on_close)
-        evio_on_error(events[i].data.ptr);
-      } else {
-        // no error, then it's an active event(s)
-        if (events[i].events & EPOLLOUT) {
-          evio_on_ready(events[i].data.ptr);
-        }
-        if (events[i].events & EPOLLIN)
-          evio_on_data(events[i].data.ptr);
-      }
-    } // end for loop
-  } else if (active_count < 0) {
-    return -1;
-  }
-  return active_count;
-}
-
-#else
-/* *****************************************************************************
-BSD `kqueue` implementation
-***************************************************************************** */
-#include <sys/event.h>
-
-/**
-Creates the `epoll` or `kqueue` object.
-*/
-intptr_t evio_create() { return evio_fd = kqueue(); }
-
-/**
-Removes a file descriptor from the polling object.
-*/
-int evio_remove(int fd) {
-  struct kevent chevent[3];
-  EV_SET(chevent, fd, EVFILT_READ, EV_DELETE, 0, 0, NULL);
-  EV_SET(chevent + 1, fd, EVFILT_WRITE, EV_DELETE, 0, 0, NULL);
-  EV_SET(chevent + 2, fd, EVFILT_TIMER, EV_DELETE, 0, 0, NULL);
-  return kevent(evio_fd, chevent, 3, NULL, 0, NULL);
-}
-
-/**
-Adds a file descriptor to the polling object.
-*/
-int evio_add(int fd, void *callback_arg) {
-  struct kevent chevent[2];
-  EV_SET(chevent, fd, EVFILT_READ, EV_ADD | EV_ENABLE | EV_CLEAR, 0, 0,
-         callback_arg);
-  EV_SET(chevent + 1, fd, EVFILT_WRITE, EV_ADD | EV_ENABLE | EV_CLEAR, 0, 0,
-         callback_arg);
-  return kevent(evio_fd, chevent, 2, NULL, 0, NULL);
-}
-
-/**
-Creates a timer file descriptor, system dependent.
-*/
-intptr_t evio_open_timer() {
-#ifdef P_tmpdir
-  char template[] = P_tmpdir "evio_facil_timer_XXXXXX";
-#else
-  char template[] = "/tmp/evio_facil_timer_XXXXXX";
-#endif
-  return mkstemp(template);
-}
-
-/**
-Adds a timer file descriptor, so that callbacks will be called for it's events.
-*/
-intptr_t evio_add_timer(int fd, void *callback_arg,
-                        unsigned long milliseconds) {
-  struct kevent chevent;
-  EV_SET(&chevent, fd, EVFILT_TIMER, EV_ADD | EV_ENABLE, 0, milliseconds,
-         callback_arg);
-  return kevent(evio_fd, &chevent, 1, NULL, 0, NULL);
-}
-
-/** Rearms the timer. Required only by `epoll`.*/
-void evio_reset_timer(int timer_fd) { (void)timer_fd; }
-
-/**
-Reviews any pending events (up to EVIO_MAX_EVENTS) and calls any callbacks.
- */
-int evio_review(const int timeout_millisec) {
-  if (evio_fd < 0)
-    return -1;
-  struct kevent events[EVIO_MAX_EVENTS];
-
-  const struct timespec timeout = {.tv_sec = (timeout_millisec / 1024),
-                                   .tv_nsec =
-                                       ((timeout_millisec % 1024) * 1000000)};
-  /* wait for events and handle them */
-  int active_count =
-      kevent(evio_fd, NULL, 0, events, EVIO_MAX_EVENTS, &timeout);
-
-  if (active_count > 0) {
-    for (int i = 0; i < active_count; i++) {
-      if (events[i].flags & (EV_EOF | EV_ERROR)) {
-        // errors are hendled as disconnections (on_close)
-        evio_on_error(events[i].udata);
-      } else {
-        // no error, then it's an active event(s)
-        if (events[i].filter == EVFILT_WRITE) {
-          evio_on_ready(events[i].udata);
-        }
-        if (events[i].filter == EVFILT_READ || events[i].filter == EVFILT_TIMER)
-          evio_on_data(events[i].udata);
-      }
-    } // end for loop
-  } else if (active_count < 0) {
-    if (errno == EINTR)
-      return 0;
-    return -1;
-  }
-  return active_count;
-}
-
-#endif /* system dependent code */

data/ext/iodine/evio.h

@@ -9,9 +9,9 @@ Feel free to copy, use and enjoy according to the license provided.
 #include <stdlib.h>
 
 /**
-This is an `epoll` / `kqueue` edge triggered wrapper, allowing for portability
-between BSD and Linux polling machanisms as well as routing events to hard-coded
-callbacks (weak function symbols) instead of the polling return values.
+This is an `epoll` / `kqueue` ONE-SHOT polling wrapper, allowing for portability
+between BSD and Linux polling machanisms and routing events to hard-coded
+callbacks (weak function symbols).
 
 The callbacks supported by thils library:
 
@@ -23,8 +23,16 @@ The callbacks supported by thils library:
 */
 #define H_FACIL_EVIO_H
 #define LIB_EVIO_VERSION_MAJOR 0
-#define LIB_EVIO_VERSION_MINOR 1
-#define LIB_EVIO_VERSION_PATCH 2
+#define LIB_EVIO_VERSION_MINOR 2
+#define LIB_EVIO_VERSION_PATCH 0
+
+#if defined(__linux__)
+#define EVIO_ENGINE_EPOLL 1
+#elif defined(__APPLE__) || defined(__unix__)
+#define EVIO_ENGINE_KQUEUE 1
+#else
+#error This library currently supports only Unix based systems with kqueue or epoll (i.e. Linux and BSD)
+#endif
 
 #ifdef __cplusplus
 extern "C" {
@@ -34,7 +42,14 @@ extern "C" {
 #define EVIO_MAX_EVENTS 64
 #endif
 #ifndef EVIO_TICK
-#define EVIO_TICK 256 /** in milliseconsd */
+#define EVIO_TICK 512 /** in milliseconsd */
+#endif
+
+#if (EVIO_MAX_EVENTS & 1)
+#error EVIO_MAX_EVENTS must be an EVEN number.
+#endif
+#if EVIO_MAX_EVENTS <= 3
+#error EVIO_MAX_EVENTS must be an GREATER than 4.
 #endif
 
 /**
@@ -61,8 +76,12 @@ Returns -1 on error, otherwise returns the number of events handled.
 */
 int evio_review(const int timeout_millisec);
 
+/** Waits up to `timeout_millisec` for events. Events aren't reviewed. */
+int evio_wait(const int timeout_millisec);
+
 /**
-Closes the `epoll` / `kqueue` object, releasing it's resources.
+Closes the `epoll` / `kqueue` object, releasing it's resources (important if
+forking!).
 */
 void evio_close(void);
 
@@ -72,11 +91,12 @@ returns true if the evio is available for adding or removing file descriptors.
 int evio_isactive(void);
 
 /* *****************************************************************************
-Adding and removing normal file descriptors.
+Adding and removing normal file descriptors (ONE SHOT).
 */
 
 /**
-Adds a file descriptor to the polling object.
+Adds a file descriptor to the polling object (ONE SHOT), both for read / write
+readiness.
 
 Returns -1 on error, otherwise return value is system dependent and can be
 safely ignored.
@@ -84,12 +104,27 @@ safely ignored.
 int evio_add(int fd, void *callback_arg);
 
 /**
-Removes a file descriptor from the polling object.
+Adds a file descriptor to the polling object (ONE SHOT), to be polled for
+incoming data (`evio_on_data` wil be called).
+
+Returns -1 on error, otherwise return value is system dependent and can be
+safely ignored.
+*/
+int evio_add_read(int fd, void *callback_arg);
+
+/**
+Adds a file descriptor to the polling object (ONE SHOT), to be polled for
+outgoing buffer readiness data (`evio_on_ready` wil be called).
 
-Returns -1 on error, otherwise return value is system dependent. If the file
-descriptor did exist in the polling object, it isn't an error.
+Returns -1 on error, otherwise return value is system dependent and can be
+safely ignored.
 */
-int evio_remove(int fd);
+int evio_add_write(int fd, void *callback_arg);
+
+/**
+Removes a file descriptor from the polling object.
+*/
+void evio_remove(int fd);
 
 /* *****************************************************************************
 Timers.
@@ -102,21 +137,14 @@ Returns -1 on error, or a valid fd on success.
 
 NOTE: Systems have a limit on the number of timers that can be opened.
 */
-intptr_t evio_open_timer(void);
+int evio_open_timer(void);
 
 /**
 Adds a timer file descriptor, so that callbacks will be called for it's events.
 
 Returns -1 on error, otherwise return value is system dependent.
 */
-intptr_t evio_add_timer(int fd, void *callback_arg, unsigned long milliseconds);
-
-/**
-Re-arms the timer.
-
-Required only by `epoll`. `kqueue` timers will continue cycling regardless.
-*/
-void evio_reset_timer(int timer_fd);
+int evio_set_timer(int fd, void *callback_arg, unsigned long milliseconds);
 
 /* *****************************************************************************
 Callbacks - override these.