BBN-V6/doc/ipc/await

.nh
.ls 2
.bl 10

.bl 10
.ce
\fBIPC Specification\fR
.pn 1
.he 1 ''%''
.bp
.bl 5
.ce
\fBCAPACITY\fR
.bl 3
.pg
The \fBcapac\fR system call enables a  process  to  ascertain  the
buffering status of its various I/O channels.  The usage is:
.bl 3
.ls 1
.nf
.kp
	\fBcapac(fd,bp,bl)

	int	fd;		/* file descriptor */
	int	bp[2];		/* result area */
	int	bl;		/* length of result area */\fR
.ke
.fi
.ls 2
.bl 3
.pg
The  call  returns a value of -1 if an error occurs, as with
other Unix system calls.  Otherwise, the current input and output
counts for the specified file  are  returned  in  the  first  and
second words of the result area.
.pg
For the capacity call, the result area must be at least four
bytes  in  length.   An  enhanced version of the capacity call is
planned which will allow a process with many inputs to avoid  the
overhead of doing multiple system calls for checking the capacity
of  the  various  inputs.  This version of the capacity call will
accept a table in the result area, which contains all the  file
descriptors  of  interest  to  the caller.  The table consists of
consecutive three word elements, one per  file  descriptor.   The
fact  that  the  result  area length is greater than two words will
identify the usage of the  enhanced  version.   An  element  will
contain the file descriptor itself, followed by two words for the
input  and  output capacities.  The call handler will simply scan
through the table filling in the elements in turn.
.pg
The counts which are  returned  to  the  process  should  be
treated  as  bounds  on  the amount of data available to read, or
buffer space available for writing.  The  actual  values  at  any
instant  may  be larger than those obtained from a capacity call,
due to activities of other processes or devices in  the  interim.
The  system does guarantee however that the amounts indicated are
minimum values, so that read or write calls of no more than those
values will not block waiting for data or buffer space.
.pg
The special value of -1 indicates that the  associated  read
or  write  operation  may  be performed without blocking, but the
actual data counts are unavailable.  Generally this occurs when a
channel has a  pending  error  which  will  cause  the  next  I/O
operation to return an error code.  It may also occur for devices
which  cannot  determine  the  size  of  incoming  data,  but can
determine that such data exists so that a read will not block.
.pg
For ports and pipes, the capacity call returns the number of
bytes which may be read or written without blocking.  Note  that,
in  the  case  of  ports,  the  system-generated  header  must be
considered as part of the data stream.  Write operations  require
that  space  be  available  for  the  sum  of the header and data
lengths in  order  to  guarantee  non-blocking.   Similarly,  the
header  size(s)  are included in the count of bytes available for
reading.
.pg
The teletype handlers provide counts for the number of bytes
of data which may be read.   Currently  no  distinction  is  made
between  normal  and  raw  modes  of teletype operation, but this
should be changed.
.pg
For output on the teletype, the count specifies  the  number
of  characters  which  the  system will permit to be added to the
device output buffer  queue.   Note  that  this  amount  may  not
actually be available if other I/O operations are in progress, so
that  it  is  not  really  a  guaranteed  amount.   However,  the
specified resources will become available  as  soon  as  possible
within  the  system,  in  contrast  to  the  case  where  a write
operation is blocked because it  exceeds  the  maximum  permitted
queue  length,  which  will  continue until the physical terminal
accepts the characters.
.pg
The IMP interface currently performs I/O operations directly
from user memory.  Consequently, write operations  never block
in  the  sense  of  waiting  for  buffers,  but rather always are
handled immediately at the interface speed.   For  write  counts,
the  capacity  call  always  returns  -1, indicating that a write
operation will succeed.   Note  that  this  precludes  permitting
several related processes to simultaneously write to the same IMP
interface,  unless they use some other mechanism for coordinating
their usage.  For reading, the device driver knows only that  the
interface  has  a  message  available.  Hence, it returns -1 when
this is the  case.   A  subsequent  read  operation  will  always
complete to the point where the supplied data buffer fills or the
interface indicates the end of the message.
.bp
.bl 5
.ce
\fBAWAIT\fR
.bl 3
.pg
The \fBawait\fR facility uses three system calls; \fBawtenb\fR, \fBawtdis\fR,
and \fBawt\fR.
.bl 2
\fBAWTENB\fR
.bl
.pg
The \fBawtenb\fR call is used by a process to indicate that it  is
interested  in  activity on a specified I/O channel.  The channel
is identified by a file descriptor, which is  mapped  within  the
kernel to an inode.
.bl 3
.ls 1
.nf
.kp
	\fBawtenb(fd)

	int	fd;		/* file descriptor */\fR
.ke
.fi
.ls 2
.bl 3
.pg
A  -1  return  value indicates an error.  The implementation
limits the number of processes which may simultaneously have  any
particular inode enabled to some value set at system generation
time.  Our current value is 2, reflecting the common usage of the
mechanism  for controlling interprocess communication between two
processes.  Attempts  to  enable  an  already-enabled  inode  are
ignored.
.pg
Note  that  several  file  descriptors may refer to the same
inode.  Also note that  inodes  have  no  inherent  direction  of
transfer,  so  that,  for example, enabling a teletype input file
descriptor effectively enables  the  output  file  descriptor  as
well, since it references the same inode.
.bl 2
\fBAWTDIS\fR
.bl
.pg
The \fBawtdis\fR call disables the specified file descriptor.  The
special  case file descriptor of -1 causes all file descriptors
for the process to be disabled.
.bl 3
.ls 1
.nf
.kp
	\fBawtdis(fd)

	int	fd;		/* file descriptor */\fR
.ke
.fi
.ls 2
.bl 3
\fBAWT\fR
.bl
.pg
The \fBawt\fR call enables a process to sleep awaiting activity on
any of its enabled I/O channels.  The call also specifies a  time
in seconds, after which the process is awakened regardless of the
activity on the various channels.
.bl 3
.ls 1
.nf
.kp
	\fBawt(tim)

	int	tim;		/* time in seconds */\fR
.ke
.fi
.ls 2
.bl 3
.pg
As  always,  a  -1  return  indicates  an error.  No special
errors are associated with await other than the normal Unix error
codes.
.pg
The operation of the await mechanism can be  modelled  as  a
single  bit  associated  with  the  process  which indicates that
something of interest has happened.  The currently  enabled  file
descriptors  define  what is of interest at any time.  Whenever
any activity occurs within Unix associated with  an  inode  which
would  normally  awake  a process blocked waiting for that event,
the activity bit is set.  The awt call will return immediately if
the activity bit is set when it is entered.  Any  activity  which
sets  the  bit will cause the process executing an awt call to be
scheduled for running.  When a process leaves the awt  call,  the
bit is cleared.
.pg
Operationally,  a process should enable all file descriptors
which are of interest for its current  task,  perform  capacity
checks  on  each  file  descriptor  until  nothing  remains to be
processed, and call awt.  If any activity has occurred  on  those
channels since the last time the processed exited from awaiting,
it  will  immediately  exit.   Otherwise,  the  process  will  be
suspended until some such activity does occur,  or  the  supplied
time  has  elapsed.   When a process returns from an awt call, it
should use capacity to check the status of  the  various  enabled
channels, to determine the cause of the wakeup.