15.3.383  src/lib/src/lib/thread-kit/src/core-thread-kit/maildrop.api

## maildrop.api
#
# These are essentially concurrency-safe REF cells.
#
# See also:
#
#     src/lib/src/lib/thread-kit/src/core-thread-kit/oneshot-maildrop.api

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





stipulate
    package mop =  mailop;                                                              # mailop        is from   src/lib/src/lib/thread-kit/src/core-thread-kit/mailop.pkg
herein

    # This api is implemented in:
    #
    #     src/lib/src/lib/thread-kit/src/core-thread-kit/maildrop.pkg
    #
    api Maildrop {
        #
        Maildrop(X);

        exception  MAY_NOT_FILL_ALREADY_FULL_MAILDROP;

        make_empty_maildrop:            Void -> Maildrop(X);                            # Construct maildrop which initially has no value.
        make_full_maildrop:             X    -> Maildrop(X);                            # Construct maildrop which initially has given value X.
                                                                                        # We could equally well collapse these two into just   make_full_maildrop: Null_Or(X) -> Maildrop(X);   but whatever.

        put_in_maildrop:                (Maildrop(X), X) -> Void;                       # If maildrop is already full this raises exception MAY_NOT_FILL_ALREADY_FULL_MAILDROP.

        take_from_maildrop:             Maildrop(X) -> X;                               # Leaves maildrop empty.
        take_from_maildrop':            Maildrop(X) -> mop::Mailop(X);

        nonblocking_take_from_maildrop: Maildrop(X) -> Null_Or(X);                      # Used (only) in   src/lib/std/src/posix/winix-data-file-io-driver-for-posix.pkg

        get_from_maildrop:              Maildrop(X) -> X;                               # Leaves maildrop unchanged.
        get_from_maildrop':             Maildrop(X) -> mop::Mailop(X);

        nonblocking_get_from_maildrop:  Maildrop(X) -> Null_Or(X);                      # Used (only) in   src/lib/src/lib/thread-kit/src/core-thread-kit/threadkit-unit-test.pkg

        maildrop_swap:                  (Maildrop(X), X) -> X;
        maildrop_swap':                 (Maildrop(X), X) -> mop::Mailop(X);

        same_maildrop:                  (Maildrop(X), Maildrop(X)) -> Bool;

        # Convenience fn for readability.
        # These currently just wrap Maildrop(Void):
        #
        make_run_gun
            :
            Void
            ->
            { run_gun':         mop::Run_Gun,                                           # We use this as a barrier for all microthreads in a graph to block on post-configuration until it is time for them to run.
              fire_run_gun:     Void -> Void
            };

        make_end_gun
            :
            Void
            ->
            { end_gun':         mop::End_Gun,                                           # Used to signal a graph of microthreads to shut down.
              fire_end_gun:     Void -> Void
            };

        maildrop_to_string:             (Maildrop(X), String) -> String;                # Debug support. Input string is a label.

    };
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.