Source

parvel / lwt_mq_parvel.mli

Full commit
(* -*- Mode: Caml; indent-tabs-mode: nil -*- *)
(******************************************************************************)
(* Lightweight thread library for Objective Caml
 * http://www.ocsigen.org/lwt
 * Interface Lwt_mon
 ******************************************************************************
 * Copyright (c) 2009, Metaweb Technologies, Inc.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * * Redistributions of source code must retain the above copyright
 * notice, this list of conditions and the following disclaimer.
 * * Redistributions in binary form must reproduce the above
 * copyright notice, this list of conditions and the following
 * disclaimer in the documentation and/or other materials provided
 * with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY METAWEB TECHNOLOGIES ``AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL METAWEB TECHNOLOGIES BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
 * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
 * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
 * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 ******************************************************************************)

(* Modified for "Parvel" project: http://bitbucket.org/gds/parvel/ *)

(** Message queues *)

(** based on code for:

    "Mailbox" variables implement a synchronising variable, used for
    communication between concurrent threads.

    This code adapted from
    {{:http://eigenclass.org/hiki.rb?cmd=view&p=lightweight-threads-with-lwt}Comparing lightweight threads (eigenclass.org)}
*)

type t 'a;
  (** The type of a message queue (MQ). MQs are used to
      communicate values between threads, sometimes synchronously,
      sometimes asynchronously (it depends on the count of messages
      in the MQ and on its [block_limit])
      The type parameter specifies the type of the value propagated from
      [put] to [take]. *)

value create : unit -> t 'a;
  (** [create ()] creates a new empty MQ. *)

value put : t 'a -> 'a -> Lwt.t bool;
  (** [put mvar value] puts a value into a MQ. This
      value will remain in the MQ until [take] is called to
      remove it.
      If MQ has less than [block_limit] messages in it already,
      the [put] will not block and will return [True].
      Otherwise, the current thread will block until someone will
      read messages from MQ.
      If there are more than [fail_limit] writers, [put] will fail,
      message won't be put into MQ and [False] will be returned
      immediately. *)

value take : t 'a -> Lwt.t 'a;
  (** [take mvar] will take next currently available value from the
      MQ. If no value is currently available, the current thread
      will block, awaiting a value to be [put] by another thread. *)

(*
value will_put_block : t 'a -> bool;
  (** [will_put_block mvar] returns true if next [put mvar] will block
      the current thread *)
*)

value have_any_reader : t 'a -> bool;
  (** [have_any_reader mvar] returns true if there exists any
      thread waiting for the [mvar] *)

(** Each MQ has two limits, initially filled with default values.
    "Block limit" is the number of messages can be added to an
    empty MQ without blocking, "fail limit" is the number of
    blocked threads (when MQ is filled up to "block limit") that
    can wait until MQ will allow them to add message and successfully
    return.  If there will be more than "block limit" sent messages
    and "fail limit" waiting threads, next [put] calls will fail
    with exception [Full].
*)

value set_block_limit : t 'a -> int -> unit;
value set_fail_limit : t 'a -> int -> unit;