## 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/poll.c
# The Mythryl side is in
# src/lib/std/src/winix/winix-io.api# src/lib/std/src/posix/winix-io.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.api# src/lib/std/socket.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.pkgstipulate
package psx = posix_1003_1b; # posix_1003_1b is from src/lib/std/src/posix-1003.1b/posix-1003-1b.pkgherein
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::io::Io_Descriptor, Void -> Void)
| IOD_IS_WRITE_READY (winix::io::Io_Descriptor, Void -> Void)
| IOD_HAS_OOBD_READY (winix::io::Io_Descriptor, Void -> Void)
| STREAM_IS_READ_READY (file::Input_Stream, Void -> Void)
| STREAM_IS_WRITE_READY (file::Output_Stream, Void -> Void)
| BINARY_STREAM_IS_READ_READY (data_file::Input_Stream, Void -> Void)
| BINARY_STREAM_IS_WRITE_READY (data_file::Output_Stream, Void -> Void)
| SOCKET_IS_READ_READY (socket::Socket( A_af, A_sock_type ), Void -> Void)
| SOCKET_IS_WRITE_READY (socket::Socket( A_af, A_sock_type ), Void -> Void)
| SOCKET_HAS_OOBD_READY (socket::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::io::Io_Descriptor -> (Void -> Void) -> When_Rule( A_af, A_sock_type);
iod_is_write_ready: winix::io::Io_Descriptor -> (Void -> Void) -> When_Rule( A_af, A_sock_type);
iod_has_oobd_ready: winix::io::Io_Descriptor -> (Void -> Void) -> When_Rule( A_af, A_sock_type);
stream_is_read_ready: file::Input_Stream -> (Void -> Void) -> When_Rule( A_af, A_sock_type);
stream_is_write_ready: file::Output_Stream -> (Void -> Void) -> When_Rule( A_af, A_sock_type);
binary_stream_is_read_ready: data_file::Input_Stream -> (Void -> Void) -> When_Rule( A_af, A_sock_type);
binary_stream_is_write_ready: data_file::Output_Stream -> (Void -> Void) -> When_Rule( A_af, A_sock_type);
socket_is_read_ready: socket::Socket( A_af, A_sock_type ) -> (Void -> Void) -> When_Rule( A_af, A_sock_type);
socket_is_write_ready: socket::Socket( A_af, A_sock_type ) -> (Void -> Void) -> When_Rule( A_af, A_sock_type);
socket_has_oobd_ready: socket::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-2012,
## released under Gnu Public Licence version 3.