lib/libasync.h

/*
copyright: Boaz segev, 2015
license: MIT

Feel free to copy, use and enjoy according to the license provided.
*/
#ifndef LIBASYNC_H
#define LIBASYNC_H

#define LIBASYNC_VERSION 0.2.0

// defines the type async_p (async pointer).
// the structure is defined to contain the thread pool's internal data as well
// as provide type safety.
typedef struct Async* async_p;

// The Async global variable contains the public API offered by the library.
extern const struct AsyncAPI {
  // the Async.new(threads, on_init_thread) creates a thread pool and
  // returns a pointer to a new Async struct object.
  //
  // **threads** (int) is the number of worker threads to be spawned.
  //
  // **on_thread_init** (func)(async_p, void*) is a callback that each new
  // working thread will call when it is first initialized.
  //
  // **arg** (void *) a pointer with datat that will be passed tp the init
  // callback.
  //
  // Forking the thread pool results in undefined behavior (create after `fork`)
  // although it's fairly likely that only the main process will handle tasks.
  // This is due to the fact that the thread pool uses pipes instead of mutexes.
  //
  // More than one pool can be created.
  //
  // Threads that crash are re-spawned by a "watch-dog" (sentinal) thread.
  //
  // returns NULL on failure.
  async_p (*new)(int threads,
                 void (*on_thread_init)(async_p async, void* arg),
                 void* arg);
  /**
  Asyn.run(async, task, arg) sends tasks to the asynchronous event queue.

  Returns -1 on error, otherwise returns 0.
 */
  int (*run)(async_p self, void (*task)(void*), void* arg);
  /** Async.signal(async) will gracefully signal the async object to finish up.
   */
  void (*signal)(async_p self);
  /** Async.wait(async) will wait for the async object to, without sending a
  signal. */
  void (*wait)(async_p self);
  /** Async.finish(async) will gracefully close down the async object,
  completing any scheduled tasks and freeing any related resources.

  This function will wait for all scheduled tasks to complete before it
  returns.

  This is equivilent to calling: `Async.signal(async); Async.wait(async);`
  */
  void (*finish)(async_p self);
  // Async.kill(async) will destroy the async object, freeing all memory and
  // destroying the queue. Some background tasks might run to completion, but
  // not all.
  void (*kill)(async_p self);
} Async;

#endif /* end of include guard: LIBASYNC_H */