sysdoc/clo.100

   1 -*-Text-*-                                              Alan 12/31/83
   2 Copyright (c) 1999 Massachusetts Institute of Technology
   3
   4 This program is free software; you can redistribute it and/or modify
   5 it under the terms of the GNU General Public License as published by
   6 the Free Software Foundation; either version 3 of the License, or (at
   7 your option) any later version.
   8
   9 This program is distributed in the hope that it will be useful, but
  10 WITHOUT ANY WARRANTY; without even the implied warranty of
  11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12 General Public License for more details.
  13
  14 You should have received a copy of the GNU General Public License
  15 along with this program; if not, write to the Free Software
  16 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  17 ------------------------------
  18
  19
  20 Here is what I know about the core link device(s).
  21
  22 The core link device is a primitive mechanism for connecting two jobs
  23 together with a uni-directional stream.  The basic idea is very simple:
  24 suppose job A opens CLO:FOO;BAR BAZ for input and job B opens
  25 CLO:FOO;BAR BAZ for output, then by virtue of the fact that they used the
  26 same name (FOO;BAR BAZ) they are connected together and anything job B
  27 happens to output to its channel will be what job A reads from its channel.
  28 For many simple hacks, that's all you really need to know about it!
  29
  30 The core link device is not a random access device.  Only the most basic
  31 system calls are supported (like OPEN, IOT, SIOT, STATUS, RFNAME, and
  32 CLOSE).  There is no way for either job to cause the other to receive a
  33 second word interrupt.  For more advanced applications where a more
  34 complicated interface is desired the JOB device can be used.  See
  35 .INFO.;ITS JOBONL (or .INFO.;ITS JOB).
  36
  37 ITS keeps an I/O buffer for each core link, so the two jobs will not
  38 actually be kept running in lock-step.  The outputting job will wait when
  39 it tries to output only if the buffer becomes full, and the inputting job
  40 will wait when it tries to input only if the buffer becomes empty.  The
  41 buffer is about 100. words long.  Because of this buffering it is not
  42 necessary for both jobs to open their channels in identical modes, one job
  43 can read (write) 36-bit words while the other is writing (reading) 7-bit
  44 characters.  [This should be contrasted with the JOB device, where ITS
  45 cannot keep any internal state for the JOB/BOJ connection because of
  46 PCLSRing considerations.]
  47
  48 If the reading job closes its input channel, the writing job's output
  49 channel acts like the NUL device.  All output is simply discarded.  If the
  50 writing job closes its output channel, the reading job's input channel acts
  51 like it has reached end of file (after it has read whatever remained in the
  52 buffer of course).  [Actually, in .UII mode if you IOT beyond end of file
  53 it starts returning random 36-bit words.  It should be fixed to generate an
  54 IOC interrupt like other devices do at EOF in .UII mode.  I guess it really
  55 doesn't matter much since you don't open things in image mode unless you
  56 know exactly what they are anyway...]
  57
  58 There are actually 4 core link devices: CLO (Core Link Open), CLU (Core
  59 Link Use), CLI (Core Link Interrupt), and CLA (Core Link Answer).  The
  60 differences between them all have to do with what happens when you open
  61 them.  In fact, after you have completed the process of opening a channel
  62 with any of these devices, an RFNAME call on that channel will always
  63 report that it is the CLO device, since from that point on they all behave
  64 identically.
  65
  66 In order match up jobs that desire to use the core link device, ITS
  67 maintains a table called the "core link directory".  At any given time the
  68 core link directory contains a number of "core links".  Each core link has
  69 three names: an SNAME, a first name, and a second name (SNAME;NAME1 NAME2).
  70
  71 When a job tries to open CLO:FOO;BAR BAZ, ITS searches the core link
  72 directory for a core link named FOO;BAR BAZ.  If no core link is found with
  73 that name, then a new core link is created with that name and entered in
  74 the directory.  (If the core link directory gets full a %EFLDR error can be
  75 returned at this point.)
  76
  77 The CLU device behaves identically to the CLO device, except that if no
  78 existing core link has the proper name then instead of creating a new one,
  79 a file not found error is returned (%ENSFL).  Thus you should use the CLU
  80 device when you are certain that some other job has already created a core
  81 link of a given name.
  82
  83 Also potentially associated with each core link is a pair of jobs.  One for
  84 reading, and one for writing.  After an appropriately named core link has
  85 been located or created, ITS checks to see whether some other job already
  86 has this core link open in the same direction.  If so, a file locked error
  87 is returned (%ENAFL), otherwise this job is recorded as the one reading or
  88 writing the core link, and the channel is successfully opened.
  89
  90 You can list the core link directory.  Opening CLO:.FILE. (DIR) will
  91 allow you to read a table like the following:
  92
  93  SNAME  NAME1  NAME2  ALAN   A     -> ALAN   B
  94  SPAZM  FOOBAR 259    CLOSED-> ALAN   A
  95  QAZWSX FOOBAR 259    ALAN   FOOBAR-> CLOSED
  96  FOO    BAR    BAZ    CLOSED-> CLOSED
  97
  98 (Try typing CLO^F to DDT.  Probably the core link directory will be empty,
  99 so you won't seen anything interesting.)
 100
 101 This table is interpreted as follows:
 102
 103  SNAME  NAME1  NAME2  ALAN   A     -> ALAN   B
 104  ^      ^      ^      ^      ^        ^      ^
 105  |      |      |      |      |        |      |    UNAME and JNAME of
 106  |      |      |      |      |        +------+--- job reading from
 107  |      |      |      |      |                    this core link.
 108  |      |      |      |      |
 109  |      |      |      |      |   UNAME and JNAME of
 110  |      |      |      +------+---job writing into
 111  |      |      |                 this core link.
 112  |      |      |
 113  |      |      |   SNAME and first and
 114  +------+------+---second names for
 115                    this core link.
 116
 117 If no job is reading from the core link, the word CLOSED will appear after
 118 the arrow instead of a UNAME/JNAME pair.  Similarly if no job is writing
 119 into the core link, CLOSED appears before the arrow.
 120
 121 If you are trying to debug something that uses the core link device, a
 122 listing of the core link directory is a valuable debugging aid.
 123
 124 In the core link directory listing above, the core link named FOO;BAR BAZ
 125 has neither an associated reading nor writing job.  You might think that
 126 such a core link would be worthless, but this is not necessarily the case!
 127 Suppose that job A opens CLO:FOO;BAR BAZ for output intending to only
 128 transmit 100. ascii characters through the link.  Since 100. characters can
 129 easily fit in the core link's buffer, job A can output all 100. characters
 130 and close its channel before the reading job even gets as far as opening
 131 its channel.  Thus for a brief time the core link has no associated jobs.
 132
 133 Unfortunately there is no way to guarantee that any job will ever open the
 134 core link FOO;BAR BAZ for input to pick up those 100. characters.  For this
 135 reason ITS will garbage collect any core link that has not had any
 136 associated jobs for several minutes (about 5 minutes).
 137
 138 You can also delete core links from the core link directory yourself.  Thus
 139 from DDT you can type "^O CLO:FOO;BAR BAZ" to get rid of a garbage core
 140 link.  Normally there is no need to do this, since ITS will flush them
 141 eventually anyway.  [Indeed, it is a BAD idea to use this feature currently
 142 because there is a bug such that instead of deleting the core link, you
 143 sometimes cause it to become permanently locked down.  Since there are a
 144 finite number of core links (12. currently), if you do this often enough
 145 you will render the core link device unusable.]
 146
 147 A reasonable person might wonder what happens if some job tries to re-open
 148 the core link FOO;BAR BAZ for output and write more characters into it.
 149 Well, each core link actually acts as a SEQUENCE of files separated by
 150 end-of-file markers.  If a second job opens CLO:FOO;BAR BAZ and writes more
 151 data into it, that data will be available to the SECOND job that opens that
 152 core link for input.  Thus if one job is in a loop opening the core link
 153 named FOO;BAR BAZ, outputting a single character, and then closing it
 154 again, and a second job is in a loop opening that core link, reading
 155 characters until end of file, and then closing it again, then the second
 156 job will see a sequence of single character length files.
 157
 158 We haven't yet mentioned the CLI and CLA devices.  These two devices enable
 159 one job to interrupt another job indicating that it wishes to send a
 160 message through a core link.  This is how interactive messages work on ITS.
 161
 162 The sending job opens the CLI device with first and second filenames equal
 163 to the UNAME and JNAME of the job that it wishes to interrupt.  For
 164 example, a job might try to open CLI:CSTACY HACTRN (any SNAME supplied will
 165 be ignored).  ITS then checks to see that a job named CSTACY HACTRN really
 166 does exist.  If it does, ITS checks to see that that job has enabled the
 167 %PICLI interrupt.  If it is not the case that both conditions are met, the
 168 open returns an illegal file name error (%EBDFN).  If both conditions are
 169 met, then we proceed as if we were opening CLO:_CLI_;CSTACY HACTRN.  If
 170 that succeeds, then we actually give the job CSTACY HACTRN the %PICLI
 171 interrupt, and the open succeeds.
 172
 173 The UNAME and JNAME of the sending job are now placed in the core link's
 174 I/O buffer so that the receiving job will be able to read them out before
 175 any additional data that the sender might wish to transmit.  (Note that you
 176 can only open the CLI device for output.)
 177
 178 In order to handle the %PICLI interrupt the job CSTACY HACTRN opens CLA:
 179 (any additional names supplied will be ignored).  This is like opening
 180 CLU:_CLI_;CSTACY HACTRN, except that it saves the interrupted job from
 181 having to figure out its own name.  The receiving job can now read the
 182 UNAME and JNAME of its interrupter by inputting the first two 36-bit words
 183 from the newly opened channel.
 184
 185 The jobs are now talking through an ordinary core link named
 186 _CLI_;CSTACY HACTRN.