15.3.451  src/lib/src/when.api

## when.api -- Convenience wrapper for 'poll'
#
# A large application often has to watch a number of different
# file descriptors simultaneously:  A multi-user game server
# may have multiple users on different socket connections,
# for example.
#
# Unix provides two standardized interfaces for doing so:
#   o The SysV-derived 'poll' interface;
#   o The BSD-derived 'select' interface.
# (The latter also comes in a New! Improved! 'pselect' variant.)
# 
# The Mythryl runtime binds the 'poll'interface:
# The C side is in
#     src/c/lib/posix-os/select.c
# The Mythryl side is in
#     src/lib/std/src/winix/winix-io--premicrothread.api
#     src/lib/std/src/posix/winix-io--premicrothread.pkg
#
# This low-level facility is not particularly simple to use.
#
# A higher-level 'select' wrapper is available in
#     src/lib/std/src/socket/socket--premicrothread.api
#     src/lib/std/socket--premicrothread.pkg
#     src/lib/std/src/socket/socket-guts.pkg 
# but it is only intended for use with sockets, and
# it is again not as convenient to use as one might wish.
#
# This 'when' module is a 'poll' convenience wrapper intended
# to make simple uses of 'poll' as convenient as possible.  It
# is not intended to replace the lower-level poll{.api|pkg}
# facility in all possible applications;  it is expected that
# in particularly complex cases, the lower level library will
# will still be the tool of choice.

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

# Implemented in:
#     src/lib/src/when.pkg


stipulate
    package fil =  file__premicrothread;                                # file__premicrothread          is from   src/lib/std/src/posix/file--premicrothread.pkg
    package psx =  posixlib;                                            # posixlib                      is from   src/lib/std/src/psx/posixlib.pkg
    package sok =  socket__premicrothread;                              # socket__premicrothread        is from   src/lib/std/socket--premicrothread.pkg
herein

    api When {
        #
        When_Rule (A_af, A_sock_type)
            = NONBLOCKING
            | TIMEOUT_SECS Float

            | FD_IS_READ_READY  (psx::File_Descriptor, Void -> Void)
            | FD_IS_WRITE_READY (psx::File_Descriptor, Void -> Void)
            | FD_HAS_OOBD_READY (psx::File_Descriptor, Void -> Void)

            | IOD_IS_READ_READY  (winix__premicrothread::io::Iod, Void -> Void)
            | IOD_IS_WRITE_READY (winix__premicrothread::io::Iod, Void -> Void)
            | IOD_HAS_OOBD_READY (winix__premicrothread::io::Iod, Void -> Void)

            | STREAM_IS_READ_READY  (fil::Input_Stream,  Void -> Void)
            | STREAM_IS_WRITE_READY (fil::Output_Stream, Void -> Void)

            | BINARY_STREAM_IS_READ_READY  (data_file__premicrothread::Input_Stream,  Void -> Void)
            | BINARY_STREAM_IS_WRITE_READY (data_file__premicrothread::Output_Stream, Void -> Void)

            | SOCKET_IS_READ_READY  (sok::Socket( A_af, A_sock_type ), Void -> Void)
            | SOCKET_IS_WRITE_READY (sok::Socket( A_af, A_sock_type ), Void -> Void)
            | SOCKET_HAS_OOBD_READY (sok::Socket( A_af, A_sock_type ), Void -> Void)
            ;



        # Curried wrappers for the above constructors,
        # for people who would rather do without the
        # upper-case shouting and/or the parentheses:

        timeout_secs:      Float                                           -> When_Rule( A_af, A_sock_type);

        fd_is_read_ready:  psx::File_Descriptor ->  (Void -> Void) -> When_Rule( A_af, A_sock_type);
        fd_is_write_ready: psx::File_Descriptor ->  (Void -> Void) -> When_Rule( A_af, A_sock_type);
        fd_has_oobd_ready: psx::File_Descriptor ->  (Void -> Void) -> When_Rule( A_af, A_sock_type);

        iod_is_read_ready:  winix__premicrothread::io::Iod    ->  (Void -> Void) -> When_Rule( A_af, A_sock_type);
        iod_is_write_ready: winix__premicrothread::io::Iod    ->  (Void -> Void) -> When_Rule( A_af, A_sock_type);
        iod_has_oobd_ready: winix__premicrothread::io::Iod    ->  (Void -> Void) -> When_Rule( A_af, A_sock_type);

        stream_is_read_ready:  fil::Input_Stream       ->  (Void -> Void) -> When_Rule( A_af, A_sock_type);
        stream_is_write_ready: fil::Output_Stream      ->  (Void -> Void) -> When_Rule( A_af, A_sock_type);

        binary_stream_is_read_ready:  data_file__premicrothread::Input_Stream       ->  (Void -> Void) -> When_Rule( A_af, A_sock_type);
        binary_stream_is_write_ready: data_file__premicrothread::Output_Stream      ->  (Void -> Void) -> When_Rule( A_af, A_sock_type);

        socket_is_read_ready:  sok::Socket( A_af, A_sock_type )  ->  (Void -> Void) -> When_Rule( A_af, A_sock_type);
        socket_is_write_ready: sok::Socket( A_af, A_sock_type )  ->  (Void -> Void) -> When_Rule( A_af, A_sock_type);
        socket_has_oobd_ready: sok::Socket( A_af, A_sock_type )  ->  (Void -> Void) -> When_Rule( A_af, A_sock_type);

        when:
            List( When_Rule( A_af, A_sock_type) )
            ->
            {  reads_done: Int,
              writes_done: Int,
               oobds_done: Int
            };
    };
end;

## Copyright (c) 2008 Jeffrey S Prothero
## Subsequent changes by Jeff Prothero Copyright (c) 2010-2015,
## released per terms of SMLNJ-COPYRIGHT.