diff options
Diffstat (limited to 'sys/etc/doc')
| -rw-r--r-- | sys/etc/doc/Proc.hlp | 22 | ||||
| -rw-r--r-- | sys/etc/doc/error.hlp | 51 | ||||
| -rw-r--r-- | sys/etc/doc/etc.hd | 29 | ||||
| -rw-r--r-- | sys/etc/doc/etc.men | 24 | ||||
| -rw-r--r-- | sys/etc/doc/psio.doc | 275 |
5 files changed, 401 insertions, 0 deletions
diff --git a/sys/etc/doc/Proc.hlp b/sys/etc/doc/Proc.hlp new file mode 100644 index 00000000..023a5316 --- /dev/null +++ b/sys/etc/doc/Proc.hlp @@ -0,0 +1,22 @@ + Process Control + +Connected Subprocesses + + pid = propen (process, in, out) + stat = prclose (pid) + stat = prgetline (in, lbuf) + prredir (pid, stream, new_fd) + prsignal (pid, signal) + prupdate (message) + + pid = propcpr (process, in, out) + stat = prclcpr (pid) + + + +Detached Processes + + job = propdpr (process, bkgfile) + stat = prcldpr (job) + y/n = prdone (job) + prkill (job) diff --git a/sys/etc/doc/error.hlp b/sys/etc/doc/error.hlp new file mode 100644 index 00000000..7776093f --- /dev/null +++ b/sys/etc/doc/error.hlp @@ -0,0 +1,51 @@ + +.help error, fatal, errchk, erract, iferr 2 "Error Handling Strategy" +.sh +ERROR HANDLING + + A recoverable error condition is asserted with ERROR. An irrecoverable +error condition is asserted with FATAL. Error recovery is implemented +using the IFERR and IFNOERR statements in the preprocessor language. +ERRACT may be called in an IFERR statement to cause a warning to be issued, +or to cause a particular error action to be taken. ERRCODE returns either +OK or the integer code of the posted error. + +Language support includes the IFERR and IFNOERR statements and the ERRCHK +declaration. The IFERR statement is grammatically equivalent to the IF +statement. Note that the condition to be tested in an IFERR statement may +be a procedure call or assignment statement, while the IF statement tests +a boolean expression. + + +.nf + errchk proc1, proc2, ... # errchk declaration + + iferr (procedure call or assignment statement) + <error_action_statement> + + iferr { + <any statements, including IFERR> + } then + <error_action_statement> + + +Library procedures (ERROR and FATAL cause a RETURN): + + error (errcode, error_message) + fatal (errcode, error_message) + erract (severity) + val = errcode () + + +ERRACT severity codes (<error.h>): + + EA_WARN # issue a warning message + EA_ERROR # assert recoverable error + EA_FATAL # assert fatal error +.fi + + +An arithmetic exception (X_ARITH) will be trapped by an IFERR statement, +provided the posted handler(s) return without causing error restart. +X_INT and X_ACV may only be caught by posting an exception handler with +XWHEN. diff --git a/sys/etc/doc/etc.hd b/sys/etc/doc/etc.hd new file mode 100644 index 00000000..759ba4e2 --- /dev/null +++ b/sys/etc/doc/etc.hd @@ -0,0 +1,29 @@ +# Help directory for the ETC (miscellaneous system stuff) package. + +$etc = "sys$etc/" + +brktime hlp = brktime.hlp, src = etc$brktime.x +btoi hlp = btoi.hlp, src = etc$btoi.x +clktime hlp = clktime.hlp, src = etc$clktime.x +cnvdate hlp = cnvdate.hlp, src = etc$cnvdate.x +cnvtime hlp = cnvtime.hlp, src = etc$cnvtime.x +cputime hlp = cputime.hlp, src = etc$cputime.x +envgetb hlp = envget.hlp, src = etc$envgetb.x +envgeti hlp = envget.hlp, src = etc$envgeti.x +envgets hlp = envget.hlp, src = etc$envgets.x +erract hlp = erract.hlp, src = etc$erract.x +errcode hlp = errcode.hlp, src = etc$errcode.x +error hlp = error.hlp, src = etc$error.x +getuid hlp = getuid.hlp, src = etc$getuid.x +itob hlp = itob.hlp, src = etc$itob.x +lpopen hlp = lpopen.hlp, src = etc$lpopen.x +main hlp = main.hlp, src = etc$main.x +onerror hlp = onerror.hlp, src = etc$onerror.x +onexit hlp = onexit.hlp, src = etc$onexit.x +oscmd hlp = oscmd.hlp, src = etc$oscmd.x +qsort hlp = qsort.hlp, src = etc$qsort.x +sys_ptime hlp = sys_ptime.hlp, src = etc$sys_ptime.x +syserr hlp = syserr.hlp, src = etc$syserr.x +tsleep hlp = tsleep.hlp, src = etc$tsleep.x +urand hlp = urand.hlp, src = etc$urand.x +xwhen hlp = xwhen.hlp, src = etc$xwhen.x diff --git a/sys/etc/doc/etc.men b/sys/etc/doc/etc.men new file mode 100644 index 00000000..5ed6f4ad --- /dev/null +++ b/sys/etc/doc/etc.men @@ -0,0 +1,24 @@ + brktime - Convert a long integer time into year, month, day, etc. + btoi - Boolean to integer + clktime - Get the clock time + cnvdate - Convert long integer time to date string (short format) + cnvtime - Convert long integer time to time string (long format) + cputime - Get the CPU time consumed by the process + envget[bis] - Get a boolean, integer, or string valued environment variable + erract - Take an error action for a previously posted error + errcode - Get the error code of the posted error + error - Post an error and take an error action + getuid - Get the name of the runtime user of a program + itob - Convert integer to boolean + lpopen - Open the line printer as a file + main - The IRAF Main + onerror - Post a procedure to be executed if error recovery occurs + onexit - Post a procedure to be executed upon process shutdown + oscmd - Send a command to the host operating system + qsort - General quick sort for any data structure + sys_mtime - Mark the time (for timing programs) + sys_ptime - Print the elapsed time since last mark + syserr - Post a system error and take an error action + tsleep - Delay process execution + urand - Uniform random number generator + xwhen - Post an exception handler diff --git a/sys/etc/doc/psio.doc b/sys/etc/doc/psio.doc new file mode 100644 index 00000000..d0f34c9a --- /dev/null +++ b/sys/etc/doc/psio.doc @@ -0,0 +1,275 @@ +.help pr_psio +.nf __________________________________________________________________________ +PR_PSIO -- Pseudofile i/o for a process. Process an i/o request for the +specified pseudofile stream of the specified process. Called either to read +command input from the CLIN of a process, or to process a read or write +request to a pseudofile of a process. + + +1. Introduction + + Pseudofile i/o in a multiprocess configuration, e.g., for the graphics +streams, is quite complex and difficult to explain briefly. I have tried to +cover the major points here but warn the reader that it is not going to be easy +to understand the flow of data and control involved. The problem is a difficult +one due to the nature of the IPC protocol and the complexity of the three +process architecture required when an external graphics kernel is used. The +discussion herein is not complete but should as least give the reader some +idea of what is going on. + + +2. Pseudofile I/O + + While a task is running the CL will be reading command input from the task. +This read eventually resolves into a call to PR_PSIO on the CLIN for the +process. When pseudofile i/o occurs, e.g., the process writes to STDOUT or +STDERR, an XMIT or XFER directive will be seen in the CLIN input from the +process. If we are directed to XMIT to an ordinary file our task is relatively +easy, i.e., we read the data block from CLIN and write it to the output file. +A directive to read from the standard input is also easy, i.e., we read from +the standard input of the parent (assuming i/o is not redirected) and write +the data block to the CLOUT of the process preceded by a count of the number +of chars. + + +2.1 I/O to a Graphics Stream + + If we are directed to read or write a graphics stream our task is somewhat +more difficult. The standard graphics streams STDGRAPH, STDIMAGE, and STDPLOT +differ from other pseudofiles in that the streams are both readable and +writable, provided all data is used up before switching modes. A graphics +stream may be connected to a file if output is being spooled, to the builtin +STDGRAPH kernel if the graphics device is the graphics terminal, or to a +graphics kernel resident in an external subprocess. + +If a graphics stream is redirected to a spool file we merely copy output to +the file and reading is forbidden. If output is to an external graphics +kernel but is unfiltered (no workstation transformation, e.g., for STDPLOT), +we merely copy data blocks on to the subprocess but the protocol involved +is nontrivial. If output is to the builtin STDGRAPH kernel or to an +external interactive kernel, output must be filtered through GIOTR before +being written to the local or remote graphics kernel. Graphics input is +also possible and is handled similarly but without need to call GIOTR. + +Before reading or writing a graphics stream GIO will send a special directive to +PR_PSIO to connect a kernel to the stream. This directive is passed to PR_PSIO +via an XMIT to the special pseudofile PSIOCONTROL. The data passed in the +XMIT call will be the GKI control instruction to be executed by PSIO. There +are currently three such directives, i.e., OPENWS, SETWCS, and GETWCS. Each +such directive is included in the normal metacode stream as well, but by +writing to a special pseudofile we avoid the need to have PR_PSIO scan each +metacode stream for control instructions, a fairly expensive operation if a +lot of data is involved. + + +2.1.1 Graphics Stream Dataflow + + A frame buffer is associated with each graphics stream in the parent +process. If graphics output (metacode) is being filtered, each output record +is appended to the frame buffer and then GIOTR is called to filter the new +instructions. GIOTR writes the filtered metacode stream either directly to +the builtin kernel or to the graphics output pseudofile stream of the parent +process. + +Output to the builtin kernel is easy to understand: GIOTR merely calls the +kernel to execute the transformed instruction. If output is to an external +kernel we unfortunately cannot simply write to the kernel because we require +that the graphics kernel task be a conventional task callable from either +the CL or by the graphics system, i.e., by PL_PSIO. We must buffer the +transformed output metacode and pass it on to the kernel process only when +requested to do so by an XFER command from the kernel. + +This buffering is done in a somewhat tricky way which makes it look like we +are writing to a simple file, and which allows us to use conventional READ and +WRITE calls to access the graphics stream. GIOTR, if not writing to the +builtin kernel, will write to one of the three graphics streams of the parent +process, i.e., to STDGRAPH, STDIMAGE, or STDPLOT. The graphics stream of the +parent is logically connected to the same stream in the kernel process. We +arrange things such that data may be written or read into the FIO buffer +associated with the stream, but the buffer will never actually be flushed, +since this would cause the contents to appear as garbage on the user terminal. + +The sequence of events for an XMIT to STDGRAPH with an external kernel is as +follows: + + + The parent process (CL) blocks, waiting for a read on the IPC + channel to the graphics task. + + Graphics task writes to stdgraph. + FIO flushes stdgraph buffer through IPC channel. + + PR_PSIO (in the parent) sees XMIT to stdgraph. + Parent reads data record from IPC channel, appending the + data record to the frame buffer for the stream. + + PR_PSIO calls GIOTR to process the new metacode. + GIOTR writes the transformed metacode instructions to the stdgraph + stream of the parent and returns control to PR_PSIO. + + PR_PSIO rewinds the stdgraph buffer in preparation for a read and + stacks the pending XMIT request and directs its command input + to the IPC of the kernel process. + + The kernel process sends zero or more XMIT or XFER requests to + the parent to read or write pseudofile streams other than + stdgraph. + The kernel process sends an XFER request to the parent to read + from stdgraph. + The parent reads the data record from the stdgraph FIO buffer + and passes it on to the kernel, completing the XFER request + of the kernel as well as the original XMIT request of the + graphics task. + + The parent process (CL) blocks, waiting for a read on the IPC + channel to the graphics task. + + +The sequence of operations for an XFER request from the graphics task is +as follows. + + The parent process (CL) blocks, waiting for a read on the IPC + channel to the graphics task. + + The parent receives an XFER request from the graphics task. + If there is any data in the stdgraph buffer the parent returns + that to the graphics task, otherwise the PR_PSIO procedure + pushes an XFER request and redirects its input to the + graphics kernel. + + The kernel process sends zero or more XMIT or XFER requests to + the parent to read or write pseudofile streams other than + stdgraph. + The kernel process sends an XMIT request to the parent to write + to stdgraph. + The parent reads the data block from the IPC channel to the kernel + and writes it to stdgraph, completing the XMIT request. + + The parent pops the XFER request and copies the data in the stdgraph + buffer to the graphics task, completing the original XFER request. + + The parent process (CL) blocks, waiting for a read on the IPC + channel to the graphics task. + + +In summary, the principal data buffers involved in pseudofile i/o to a graphics +stream are the frame buffer, used by GIOTR to spool the metacode instructions +for a graphics frame, and the FIO buffer for the graphics stream, used to +pass data between XMIT/XFER request pairs from cooperating processes at +opposite ends of a graphics stream. + + +3. Summary + + The actual code required to implement all this is probably easier to +understand than the English description. To summarize the justification for +the complexity of the scheme we have adopted: + + [1] The graphics kernel task is a conventional CL callable task with + parameters etc., usable to process metacode from a metafile or from + a pipe as well as callable by PR_PSIO. The conventional IPC protocol + is used in the graphics kernel task. Other tasks may be resident in + the same process, saving disk and memory. + + [2] The graphics kernel may read STDIN and write STDOUT and STDERR while + processing metacode, allowing access to the graphics terminal via the + CL process, output of debugging information during operation, and + output of error messages during operation. +.endhelp ______________________________________________________________________ + + +# PR_PSIO -- Process an i/o request for the specified pseudofile stream +# of the specified process. + +procedure pr_psio (pid, active_fd) + +pid process id +fd process stream for which i/o is requested + +begin + in = pr.clin + fd = active_fd + clear stack + + # Process i/o requests from the subprocess until a request is received + # and processed for pseudofile FD. + + repeat { + while (filbuf (in) != EOF) { + determine type of request and destfd + + if (xmit request to stream destfd) { + if (graphics filtering enabled) { + read data record and append to frame buffer + call giotr to filter output to destfd + } else { + read data record from process + write record to destfd + } + if (destination is a process) { + rewind destfd buffer for read + push (fd) + push (in) + push (xmit) + fd = destfd + in = newpr.clin + next + } + + } else if (xfer request from stream destfd) { + if (destfd is a process and buffer is empty) { + push (fd) + push (in) + push (xfer) + fd = destfd + in = newpr.clin + next + } else { + read data record from destfd + write data record to process + } + + } else if (gio directive) { + if (open workstation) + connect a kernel process to a graphics stream + else if (setwcs) + save wcs for the stream + else if (getwcs) + write wcs data to the process + + } else { + destfd = CLIN + if (fd != CLIN) + error: unsolicited command input from the subprocess + } + + if (destfd == fd) { + if (stack not empty) { + pop (request) + pop (in) + pop (fd) + if (request == xfer) { + read data record from fd + write data record to process owning "in" + } + } else + break + } + } + } until (stack is empty) +end + + + +File routing: + + Each pseudofile in a subprocess is associated with a stream in the parent +process. A subprocess pseudofile may map to a real file or to a parent +pseudofile. When a subprocess is connected as a graphics kernel graphics +i/o will be via any one of the standard graphics streams STDGRAPH etc., +with said graphics stream connected to the same stream in the parent. +The subprocess streams STDIN, STDOUT, and STDERR are by default connected +to the same streams in the parent, allowing the subprocess to access the +terminal, output error messages, and so on. A graphics kernel will be able +to access the standard i/o streams even while connected as a subprocess +to filter GKI metacode. |