15.3.385  src/lib/src/lib/thread-kit/src/core-thread-kit/mailqueue.api

## mailqueue.api
#
# Unbounded queues of thread-to-thread mail messages.

# Compiled by:
#     src/lib/std/standard.lib




stipulate
    package itt =  internal_threadkit_types;                                                                            # internal_threadkit_types              is from   src/lib/src/lib/thread-kit/src/core-thread-kit/internal-threadkit-types.pkg
herein
    api Mailqueue {
        #
        Mailqueue(X);

        make_mailqueue:  itt::Microthread -> Mailqueue(X);                                                              # Argument gives the microthread which will be reading from the mailqueue -- useful for debugging and display.

        same_mailqueue:  (Mailqueue(X), Mailqueue(X)) -> Bool;

        put_in_mailqueue:              (Mailqueue(X),  X) -> Void;

        take_from_mailqueue:            Mailqueue(X) -> X;
        take_from_mailqueue':           Mailqueue(X) -> mailop::Mailop(X);

        take_all_from_mailqueue:        Mailqueue(X) -> List(X);
        take_all_from_mailqueue':       Mailqueue(X) -> mailop::Mailop(List(X));

        mailqueue_to_string:            (Mailqueue(X), String) -> String;                                               # Debug support. Input String is a human-readable name for the mailqueue.

        get_mailqueue_reader:           Mailqueue(X) -> itt::Microthread;       # Returns argument originally supplied to make_mailqueue().
        get_mailqueue_id:               Mailqueue(X) -> Int;                    # Debug support: Unique id, to allow mapping mailqueues to relevant information about them.
        get_mailqueue_length:           Mailqueue(X) -> Int;                    # Debug support.
        get_mailqueue_putcount:         Mailqueue(X) -> Int;                    # Debug support: Total number of times 'put_in_mailqueue' has been called for this mailqueue.

        drop_mailqueue_tap:            (Mailqueue(X), Ref(Void)) -> Void;       # Drop a previously registered a tap.  To minimize system impact, taps should avoid blocking:  The typical tap will increment a count or write to another mailqueue.
        note_mailqueue_tap:            (Mailqueue(X), X -> Void) -> Ref(Void);  # Register a tap which will be called each time put_in_mailqueue() is called. Return value allows later tap deletion via drop_mailqueue_tap().
    };
end;


## COPYRIGHT (c) 1989-1991 John H. Reppy
## COPYRIGHT (c) 1995 AT&T Bell Laboratories
## Subsequent changes by Jeff Prothero Copyright (c) 2010-2015,
## released per terms of SMLNJ-COPYRIGHT.