The Standard ML Basis Library

The `OS.IO` structure

The OS.IO structure provides a general interface for polling IO devices. This has been modelled after the Unix SVR4 poll interface. A poll_desc, created from an IO descriptor, can be used to test for various polling conditions.

Synopsis

signature OS_IO structure IO : OS_IO

Interface

eqtype iodesc val hash : iodesc -> word val compare : (iodesc * iodesc) -> order eqtype iodesc_kind val kind : iodesc -> iodesc_kind structure Kind : sig val file : iodesc_kind val dir : iodesc_kind val symlink : iodesc_kind val tty : iodesc_kind val pipe : iodesc_kind val socket : iodesc_kind val device : iodesc_kind end type poll_desc type poll_info val pollDesc : iodesc -> poll_desc option val pollToIODesc : poll_desc -> iodesc exception Poll val pollIn : poll_desc -> poll_desc val pollOut : poll_desc -> poll_desc val pollPri : poll_desc -> poll_desc val poll : (poll_desc list * Time.time option) -> poll_info list val isIn : poll_info -> bool val isOut : poll_info -> bool val isPri : poll_info -> bool val infoToPollDesc : poll_info -> poll_desc

Description

eqtype iodesc

an iodesc is an abstraction for an opened OS object that supports IO (e.g., file, tty, device, socket, ...). In Unix, an iodesc would correspond to a file descriptor; in DOS, it would correspond to a file handle.

Since iodesc values correspond to low-level, OS-specific objects, they are not typically created explicitly by the user, but are generated as a side-effect of the creation of a more high-level abstraction. For example, TextIO.openIn creates an instream value, from which the underlying PrimIO.reader can be accessed. This latter value may contain the corresponding iodesc value.

If the underlying operating system is known, there will usually be mechanisms for converting between iodesc values and the type of value used by the operating system. For example, the functions Posix.FileSys.fdToIOD and Posix.FileSys.iodToFD provide this service for Posix implementations, translating between iodescs and open file descriptors.

hash iod

return a hash value for the IO descriptor iod.

Implementation note:

hash must have the property that values produced are well distributed when taken modulo 2⁽ⁿ⁾ for any n.

compare (iod, iod')

returns LESS, EQUAL or GREATER when iod is less than, equal to, or greater than iod', respectively, in some underlying linear ordering on iodesc values.

eqtype iodesc_kind

This abstract type is used to represent the kind of system object that an iodesc represents. The possible values are defined in the Kind substructure.

kind iod

returns the kind of system object that the I/O descriptor iod represents. This will raise OS.SysErr if, for example, iod refers to a closed file.

structure Kind

val file

val dir

val symlink

val tty

val pipe

val socket

val device

These values represent the various kinds of system objects that an I/O descriptor might represent. The following list summarizes the intended meaning of these values:

file: A regular file in the file system. The I/O descriptor associated with a stream produced by one of the BinIO or TextIO file opening operations will always have this kind.
dir: A directory in the file system. I/O descriptors associated with file-system objects for which OS.FileSys.isDir returns true will have this kind.
symlink: A symbolic link or file system alias. I/O descriptors associated with file-system objects for which OS.FileSys.isLink returns true will have this kind.
tty: A terminal console.
pipe: A pipe to another system process.
socket: A network socket.
device: A logical or physical hardware device.

Question:

Should there also be an other value to provide an escape hatch?

type poll_desc

an abstract representation of a polling operation on an IO descriptor.

type poll_info

an abstract representation of the per-descriptor information returned by the poll operation.

pollDesc iod

create a polling operation on the given descriptor; NONE is returned when no polling is supported by the IO device.

pollToIODesc pd

return the IO descriptor that is being polled using pd.

exception Poll

pollIn pd

pollOut pd

pollPri pd

returns poll descriptor that has input (respectively, output, high-priority) polling added to the poll descriptor pd. Raises Poll if input (respectively, output, high-priority events) is not appropriate for the underlying IO device.

poll (l, opt)

polls a list of poll descriptors l. The argument opt specifies the timeout where:

NONE means wait indefinitely.
SOME(Time.zeroTime) means do not block.
SOME(t) mean timeout after time t.

This will raise OS.SysErr if, for example, one of the file descriptors refers to a closed file.

isIn info

isOut info

isPri info

returns true if input (respectively, output, priority information) is present in info.

infoToPollDesc pi

returns the underlying poll descriptor from poll information pi.

[ INDEX | TOP | Parent | Root ]