The Fred Fish Collection 1.5/ffcollection-1-5-1992-11.iso/ff_disks/200-299/ff290.lzh/IPC/Broker/READ_ME

Text File | 1989-12-11 | 10KB | 187 lines

The programs in this directory are mostly to demonstrate the IPC "Port
Broker" mechanism, in a so far somewhat rudimentary form.

    The "Broker" icon starts up the simple Port Broker needed for the demo.
    To terminate it, type ctrl-C to the window that appears when it's
    running. (Unlike the other icons in this package, this is a Tool, not
    an Xicon script.)

    The "Demo" icon runs the same programs as "IPC_Demo" in the parent
    directory, but using the Broker.  See below for more details.

There is also an IPCPort "Cleaner" program (no icon) -- described at the
end of this text. Sources for both Broker and Cleaner are in the "Sources"
directory.


IPC Port Broker
===============

The concept of the Port Broker is fairly central to this IPC system, even
though it is itself not really part of the protocol. It is a program that
will normally remain continuously resident while IPC is in use, managing
the loading of programs that provide services to others.

Any Client process that wants another (Server) process to perform some task
for it, only needs to know the True Name of the IPCPort to which it should
make its demands.  [I think the Magicians of Old had a similar notion...]
The Client does a LoadIPCPort call with that name, and -- if the port is
not already in service -- the request is passed to the Broker.  The Broker
will previously have been informed of the exact Secret Words [CLI Command]
needed to invoke the Servant of the Port, and will at once perform the
necessary deeds.

The advantages of this scheme are twofold: first, processes get started up
automatically when needed (and can terminate themselves when they decide
their usefulness is over); second, the user can configure his system with
his own choice of servers, as long as the name of a port that provides a
certain function is standardised.

                            + + +

The demo in this directory is a very simple example of the concept.  It
also neatly shows some of the problems with Simplicity...

For the demo to work, you must have started the Broker first, by clicking
on its icon.  Though you will see that this version of the broker has its
own window (courtesy of Lattice) no output will appear there.  Its only
usefulness is to let you terminate the program again by typing ctrl-C
to it.  This is one of the artefacts of Simplicity.

By the way, if you want to see what happens if you try the demo without the
broker running, go ahead.  The results pose no hazard to your system's
health (and should be self-explanatory).

You'll find that the Broker demo uses exactly the same (stupid) Client and
Server as the "IPC_Demo" in the parent directory (which therefore must
remain available for anything at all to work).  However, unlike the latter,
it starts only the Client from the icon script, and not the Server.

The first thing the Client does is request a 'LoadIPCPort("Print_Format")'
(that's the name of the IPCPort involved); if there is no Server for the
port already running, a message is whipped off to the Broker, which looks
that name up in its list (a short one in this case!).  That list, by the
way, is loaded from the file "port_list" in this directory (more on this
later).  Corresponding to that name, it finds the command needed to start
the Server (from the directory "/IPC_Demo"), and fires it up.

Another consequence of Simplicity unfortunately pops up right here.  All
input and output for these programs is done (Simply) by redirecting
standard input and output to console windows.  Each window is in turn
created Active, so the last one created is the one that ends up Active.
And of course this is the Server output -- not the Client input, as we
would like.  The non-broker form of this demo avoids the difficulty just by
starting the Server first, but of course that doesn't work here.  There are
lots of ways we could rewrite the programs to avoid this, but on the other
hand it's probably a good idea to present some of the problem areas too...

If you like, you can try activating a second instance of the demo.  This
time the Server is already running, so the Client is able to get to it
immediately (and the Server naturally has no problem handling more than one
Client).  This means of course that this time we avoid the problem just
mentioned.  (You can also run multiple copies of IPC_Demo, but the results
are not as clean there because the script tries -- and fails -- to start up
a new Server each time.)

I should point out in passing that the Client start-up code was specially
written to work with or without a Broker.  This is easy to do, but in the
normal case probably wouldn't be desirable.



    *************************************************************

The Broker Code
===============

The Broker program obtains the names of IPCPorts it may have to load, and
the CLI commands it will need to load them, from a file it reads when it is
started.  The name of this file may be specified in ToolType "FILE=name" of
the icon if it is started from the WorkBench, or as a command line argument
if it is run from the CLI.  If no file is specified it will look for
"S:IPC_Port_List".  If it can't read a file, or the file is empty, it will
abort.  Otherwise it remains resident (mostly in a Wait state) until
terminated by a ctrl-C break.

As this is only a simple implementation, it just reads the file at start
up.  A more complete one will doubtless have ways of adding or changing
entries in the list at a later time.

The Broker is sent a message whenever a LoadIPCPort call in another program
cannot find a served port of the specified name already active.  The broker
looks the name up in its list (a linear search -- probably quite adequate
here); if it is found, there will be a CLI command associated with it --
to start the Server --, which the broker executes. At the same time, the
port is marked as "LOADING", so that it can accept messages.

The file format is simply a series of single-line entries, each beginning
with a port name ENCLOSED IN (double) QUOTES, followed by a space and then
the CLI command to be executed.  (A full command pathname is generally
required -- unless the command is in 'C:'; full paths are always required
for filenames used as arguments.  'ASSIGN'ing a shorthand path -- as done
in the demo -- is a useful dodge here.)  Any line that doesn't begin with a
quote is simply skipped, so you can include comments if you want.

This format was chosen simply because it was easy to implement -- other
brokers might define quite a different one.  Multiple line commands, or
wild card matching, might be allowed, for instance.  And as the design
evolves, other sorts of capabilities are sure to be added.  Maybe the
Broker might have a "button panel" for launching Clients too, or for
sending specific messages.  It certainly will need an ARexx interface.  The
reserved IPCPort for the Broker -- "PortBrokerPort" -- is of course
available for any other categories of message you might want to send to the
program.  Just avoid using the 'IPPL' message ID that LoaIPCPort transmits
(unless it's appropriate!).

Note that -- because of Execute()'s limitations -- there is no way for the
broker to know if the command has actually been successfully launched or
not.  So it is possible that a "LOADING" port might fail in fact to do so!
There are ways for a Brighter Broker to handle this: one simple way is to
send a dummy message to the loading port; if this isn't replied within a
certain time, it can assume the load has failed, in which case it Serves
the port itself, bounces back any pending messages with an error code, and
lets it go.

Note also that -- for similar reasons -- any text output resulting
from a command is directed to NIL: when the broker is started from an icon.
It should be possible to direct it to the window Lattice kindly opens for
us, but this is not straightforward.  Actually you probably don't really
want any command output, but if you do you can always 'RUN' it from a CLI.

    *************************************************************


Cleaner
=======

This is a small utility program to help you keep tabs on things when you're
experimenting with IPCPorts.  It combines two different functions into one
package, depending on whether you give it any command line arguments or
not. (It can only be run from the CLI.)

Invoked without any arguments, it prints a list of all the IPCPorts
currently defined, with the number of references (Clients or Servers) to
each, and any state flags set.

If you give the name of any currently valid IPCPort as an argument
(multiple items allowed) it will remove ALL the references to that port,
and the port itself. This is intended as an "Emergency Recovery" operation
only!!

If IPC programs are correctly written, they shouldn't leave excess port
references around when they leave, and if they're still running you should
NEVER remove a port from under them.  However, it's easy to forget
something while you're developing code, and to leave a reference that stays
around for ever; if this is a Server, you're really in trouble because no
other Server can then attach to the port.

If you suspect something of this sort has happened, you can check by using
Cleaner with no arguments. If you do find it to be the case, then clear up
the problem by invoking Cleaner with the name of the hung port as argument.
Of course, all processes CORRECTLY connected to the port should be
terminated before using this command.

    **************************************************************