Module Duppy

Advanced scheduler and monad for server-oriented programming.

* 

    *        The bars could not hold me;
    *        Force could not control me now.
    *        They try to keep me down, yeah!
    *        But Jah put I around.
    *        (...)
    *        Let me tell you this -
    *        I'm a duppy conqueror !
    *

}

}

*

Lee "Scratch" Perry & Bob Marley - Duppy conqueror

* *

Duppy task scheduler for OCaml.

* * Duppy is a task scheduler for ocaml. It implements a wrapper * around Unix.select. * * Using Duppy.Task, the programmer can easily submit tasks that need to wait * on a socket even, or for a given timeout (possibly zero). * * With Duppy.Async, one can use a scheduler to submit asynchronous tasks. * * Duppy.Io implements recursive easy reading and writing to a Unix.file_descr * * Finally, Duppy.Monad and Duppy.Monad.Io provide a monadic interface to * program server code that with an implicit return/reply execution flow. * * The scheduler can use several queues running concurently, each queue * processing ready tasks. Of course, a queue should run in its own thread.

type 'a scheduler

A scheduler is a device for processing tasks. Several queues might run in * different threads, processing one scheduler's tasks. * * 'a is the type of objects used for priorities.

val create : ?on_error:(exn -> Stdlib.Printexc.raw_backtrace -> unit) -> ?compare:('a -> 'a -> int) -> unit -> 'a scheduler

Initiate a new scheduler *

  • parameter compare

    the comparison function used to sort tasks according to priorities. * Works as in List.sort

val poll : Unix.file_descr list -> Unix.file_descr list -> Unix.file_descr list -> float -> Unix.file_descr list * Unix.file_descr list * Unix.file_descr list

Internal polling function. Uses `Unix.select` on windows and `poll` otherwise.

val queue : ?log:(string -> unit) -> ?priorities:('a -> bool) -> 'a scheduler -> string -> unit

queue ~log ~priorities s name * starts a queue, on the scheduler s only processing priorities p * for which priorities p returns true. * * Several queues can be run concurrently against s. *

  • parameter log

    Logging function. Default: Printf.printf "queue %s: %s\n" name *

    @param priorities

    Predicate specifying which priority to process. Default: fun _ -> _ -> true * * An exception is raised from this call when duppy's event loops has * crashed. This exception should be considered a MAJOR FAILURE. All current * non-ready tasks registered for the calling scheduler are dropped. You may * restart Duppy's queues after it is raised but it should only be used to terminate * the process diligently!!

val stop : 'a scheduler -> unit

Stop all queues running on that scheduler and wait for them to return.

module Task : sig ... end

Core task registration. * * A task will be a set of events to watch, and a corresponding function to * execute when one of the events is trigered. * * The executed function may then return a list of new tasks to schedule.

module Async : sig ... end

Asynchronous task module * * This module implements an asychronous API to Duppy.scheduler * It allows to create a task that will run and then go to sleep.

module type Transport_t = sig ... end

Module type for Io functor.

module type Io_t = sig ... end

Easy parsing of Unix.file_descr. * * With Duppy.Io.read, you can pass a file descriptor to the scheduler, * along with a marker, and have it run the associated function when the * marker is found. * * With Duppy.Io.write, the schdeduler will try to write recursively to the file descriptor * the given string.

module Io : Io_t with type socket = Unix.file_descr
module Monad : sig ... end

Monadic interface to Duppy.Io. * * This module can be used to write code * that runs in various Duppy's tasks and * raise values in a completely transparent way. * * You can see examples of its use * in the examples/ directory of the * source code and in the files * src/tools/{harbor.camlp4,server.camlp4} * in liquidsoap's code. * * When a server communicates * with a client, it performs several * computations and, eventually, terminates. * A computation can either return a new * value or terminate. For instance: * * - Client connects. * - Server tries to authenticate the client. * - If authentication is ok, proceed with the next step. * - Otherwise terminate. * * The purpose of the monad is to embed * computations which can either return * a new value or raise a value that is used * to terminate.

Some culture..

* Duppy is a Caribbean patois word of West African origin meaning ghost or spirit. * Much of Caribbean folklore revolves around duppies. * Duppies are generally regarded as malevolent spirits. * They are said to come out and haunt people at night mostly, * and people from the islands claim to have seen them. * The 'Rolling Calf', 'Three footed horse' or 'Old Higue' are examples of the more malicious spirits. *

http://en.wikipedia.org/wiki/Duppy