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

Text File | 1989-12-11 | 16KB | 329 lines

               Inter-Process Communication Standard
               ====================================

                          November 1989


This package had its origin in several months' discussion during 1988
on usenet.  The goal has been to create a standard for Inter-Process
Communication on the Amiga (briefly known as "IPC") that is flexible enough
to handle the widest possible range of applications.  The basic standard is
now fairly well fixed, though many areas are still undeveloped.

Over the past year or so there has been a considerable rise in interest in
IPC in general, and in particular ARexx has become very popular.  The
protocol described here addresses some rather different problem areas from
ARexx, and emphasizes different aspects of the communication process (like
fast communication and data structure).  I believe they both have their
place, and hopefully there will be some integration eventually.  To
distinguish this particular scheme it has become known as "PPIPC" (because
the main authors were Pete (Goodeve) and Peter (da Silva)...).  Better to
keep personalities out of it, though, and think of it as standing for
"Packet Passing IPC", or "Port Protocol IPC", or some such.

This standard is completely Public Domain, and it could lead to some
outstanding new capabilities for this machine.  This release is now based
on a shared resident library (occupying well under 2K of memory). The code
needed in an application program to make use of it should also be compact.

[I'm afraid that the sources are heavily Lattice oriented, though hooks
have been provided that should make the library, at least, work fine with
Manx/Aztec too.]



                          What is IPC ?
                          =============

The idea is to provide an alternative to the monolithic programs that have
become typical of the other personal computers, which don't have built-in
multitasking.  Rather than try to cram all sorts of features into one
loadable program, why not put them in smaller modules which run as separate
processes, and have them coordinate their activities through "Inter-Process
Communication"?  Only those modules needed for the task at hand then have
to be loaded, giving the user much more flexibility.  If the standard is
properly designed, modules from entirely different sources should be able
to talk to one another.

The basic concern is to have a message passing mechanism that is both safe
and flexible.  Messages must carry complete identification of their
contents in a standard form so that communication is always clear and
unambiguous.  Because the various communicating modules will start up, and
depart again, asynchronously, the ports through which the messages are
passed have to be managed carefully, so that there is no danger of, for
example, sending a message to a no-longer-existing port.

All these goals and concerns are discussed at much more length in
Docs/IPC.Doc.

There are demos in this package showing how IPC is intended to operate, but
they aren't perhaps as inspiring as I would like.  For my talk at BADGE on
IPC, I created a much more useful IPC suite, which displayed my "slides" on
the topic.  It comprises five modules working together: a Bitmap display
server, an ILBM (to bitmap) server, a Script Manager that determines which
slides to preload to bitmaps and sends them to the display server as
requested, and two Client programs -- one to accept commands from the
keyboard, and the other from a joystick; actually the display server is a
client as well -- it passes mouse-click generated commands to the Script
manager.  Unfortunately all this isn't really suitable for distribution at
the moment: it all works well, but the pieces were hacked together, rather
than designed, with expedient short-cuts and incosistencies; all in all,
not a shining example of how to do it.  Anyhow, the slides themselves
filled two disks!

I have also converted (and slightly extended) Peter da Silva's File
Requester into a Server, but I just haven't had time to put it into
publishable form yet.  Hopefully soon..

On the other hand, perhaps I needn't worry too much about the availability
of examples.  Dave Navas used PPIPC as the basis of his magnificent
JazzBench -- find it on Fish Disk #228.  If you haven't come across it yet,
this is a multitasking replacement for WorkBench, meaning amongst many
other things that you don't have to wait until all the icons have loaded
before you can select one. True to the spirit of IPC, too, the user can
choose modules to provide different modes of action, such as fancy window
opening and closing, or different "beeps".  In its current "alpha" version,
there are no published IPC hooks for others to hook into JazzBench, but no
doubt these will show up if Dave gets any respite from his studies...

I'm also a little appalled at the volume of verbiage that seems needed to
put over the concepts.  I guess the trouble is that it's less a program,
more a philosophy.  It certainly seems to require some evangelism, anyhow.
I've tried to organize the material so that it won't be too hard to plow
through.  I hope a few people will get inspired to try approaching some of
their programming this way.


                        What's in the package
                        =====================

Here you will find an icon to install ppipc.library in your 'LIBS:'
directory, a couple of trivial demos of the concept, and various
directories containing documentation and sources for nearly everything.

[The significance of the icons used may be obscure to people who weren't
at the BADGE meeting on IPC last year.  ...just think of Servers, Clients,
and Managers...]


Install_Library --  An "Xicon capsule" that installs "ppipc.library"
                    in the current LIBS: directory, as required before
                    any program using IPC can run.  (As with IPC_Demo,
                    below, it is actually a directory containing
                    ppipc.library and suitable text and script.)


Small_Demo      --  A very simple demo of a client and a server communicating
                    via IPC.  It has no useful function at all.

                    (Before trying to run it, you must have executed the
                    "Install_Library" icon -- see above.)

                    Clicking on the icon starts a Server that just sends
                    the text of messages it receives to standard output
                    (redirected here to a console window), and a Client
                    that accepts typed input and sends each line as a
                    message to the Server.  The IPCPort through which the
                    messages pass is named "Demo".  When you exit the
                    client by typing an EOF char ('ctrl-\'), another little
                    "Client" called "Quit" is invoked to tell the Server
                    also to terminate.

                    Explore it together with the associated sources on the
                    disk. The demo uses an Xicon script to start up the
                    Server and Client processes.  Note that IPC_Demo itself
                    is actually a directory containing all the necessary
                    files (except Xicon, which should be in the C directory
                    of this suite).


IPC_Demo        --  A less simple demo of a client and a server using
                    IPC.  It  also has no useful function  (aside from
                    illustration), though the Print Formatting Server
                    should be generally useful.

                    The Server here is one that performs numeric-to-text
                    and other formatting of message items it is sent; a
                    snmgle message can contain items of different types,
                    such as integers, floating point values, strings, and
                    (printf style) formatting strings, all of which will
                    be combined into a single output string.  Depending on
                    other instructions in the message, the output may be
                    sent to the output of the server, to a specified
                    handle, or returned as an item when the message is
                    replied.

                    The Client just puts a bunch of items (which the user
                    has no control over...) into a message and sends it off
                    for formatting; you can, however, select by keyboard
                    command whether the output goes to the Server Window,
                    to the Client window (via file handle), or is returned
                    in the message.  Rather than using a "Quit" client as
                    the previous demo does, the Client itself sends the
                    QUIT message as it terminates.

                    The comments on the previous demo also apply here.


Broker          --  A demonstration of the "Port Broker" concept.  See the
                    READ_ME file in the drawer for more information.  The
                    directory also contains a "Cleaner" utility (no icon).


Docs            --  Documents on the IPC protocol:

     IPC.doc            --  A description of the IPC concept and this
                            standard.
     Standard Flags     --  An extended description of the IPCMessage flags
                            in IPC.h.
     Standard IDs       --  The currently defined and reserved IPC Message
                            and Item IDs.


IPC_Include     --  The Main header file (IPC.h) required for applications
                    using IPC, the direct library call header for recent
                    Lattice compilers, and other files that may be of
                    general use for compilation or assembly.


Sources         --  A directory containing source files for the demo
                    program modules, plus those for the Port Broker and
                    "Cleaner" utility.  See the READ_ME file in the
                    directory.


IPC_Lib_Sources --  A directory containing the source files for the IPC
                    library routines.  See the READ_ME file in the directory
                    for contents and details.


Lattice_link_lib    -- The library call stubs required by earlier versions
                    of Lattice for linking. (Also see Libraries.)


Manx_link_lib    -- Trivially modified versions of the Lattice linkage
                    stubs that sould be suitable for assembly under Aztec.
                    An object file (ipc.lib) for Manx 3.4 is included.



Libraries       --  (Another) copy of ppipc.library, and the (Lattice
                    version) linkage routines needed by compilers previous
                    to 4.0. (IPC.lib)


 C              --  utility programs (Xicon and Most).


                                %%%%%%%%%%%%%


Brief Notes on usage:

    The PPIPC scheme is both a protocol and a Shared Resident Library,
    designed to make (direct) communication between independently written
    programs easier to manage.

    The protocol defines (in an open ended fashion) the structure of
    messages to be passed between programs, in a manner that allows any
    "Server" program that is capable of handling a particular message to
    recognize that message and process it appropriately; when the message
    is replied to the originating "Client", this program can in turn
    determine (from flags in the message) what changes have been made.
    The Library handles message passing much more securely than Exec does,
    so that, for example, a message cannot be sent to a no-longer-existing
    port.  It also provides other utilities, such as creation and deletion
    of standard IPC messages.  IPCMessages are basically Amiga Exec messages
    with a specific structure -- comprising an ID and zero or more items
    --appended to the basic message block.  This is all described in much
    more detail in IPC.Doc and the other files in Docs.

    There is at least one other semi-standard piece to the protocol -- the
    "Port Broker".  One of the standard calls to the library (LoadIPCPort)
    triggers a call to this Broker process (when one is installed) if a
    port with the requested name is not found; it is then up to the Broker
    to load a Server for this port (presumably by consulting some
    configuration file).  Only a primitive such broker exists so far
    (see Other_Sources); if you feel inspired to improve it, please go
    ahead.  One of the main tenets of IPC is that only the core should be
    fixed: people should be able to mix 'n match everything else.


    The Library is a standard disk-resident shared library, which of course
    must be installed in LIBS: before IPC can be used.  The way you call the
    library from any program you write will depend on the compiler you are
    using.  Like any other resident library, calls to it are made via offset
    jump vectors in the library node, and it must receive the parameters of
    the call in appropriate registers (see IPC_lib.fd in IPC_Include for
    the actual registers each call uses).  Most compilers require that you
    include an object library at link time, containing short stub routines
    to turn high-level language calls into jumps with the appropriate
    registers set.

    Unfortunately I only have access to Lattice C, so that this is the only
    interface immediately available.  It is provided in two forms: for
    Lattice versions 4.0 or later, you can simply include IPC_proto.h (in
    addition to IPC.h, which is always required) when you compile, and
    calls will be generated in a suitable form automatically; for earlier
    versions, you will have to link with IPC.lib (found in Libraries and
    Lattice_link_lib).

    Assembly sources have been provided to create a Manx/Aztec library,
    and an object file for Manx 3.4.  If you want 3.6 compatibility I'm
    afraid you'll have to do this yourself. If you feel tempted to generate
    linkages for other languages such as Modula-2, that would be great.

    Whatever compiler you use, you must of course do

        IPCBase = OpenLibrary("ppipc.library",2);

    before you use the library, and CloseLibrary(..) at the end.  (And the
    library pointer MUST be named IPCBase' if you intend to use any of the
    provided access mechanisms).

    I hope that's enough to get you started.  The main sources of
    information at the moment, as well as the Docs files, are the header
    file IPC.h, the demo sources, and the Library sources themselves. Have
    fun!

                                %%%%%%%%%%%%%


Acknowledgments and attributions:

This package and its contents were compiled by Pete Goodeve, who should be
flamed... er.. blamed... for all its inadequacies.  Almost all the code
here was also written by Pete.

The IPCMessage format was largely the design of Peter da Silva.

The mechanism used to manage IPCPorts safely ("use counts") was originally
suggested by Matt Dillon.

The additions to IPC.h needed to make it compatible with Manx C
were supplied by Brian Witt.  Dave Navas supplied the Manx linkage
library.

Special acknowledgment must also go to Dave Navas for his amazing JazzBench,
which aside from being a great piece of work in its own right is a perfect
example of the possibilities of IPC.

Essential criticism and suggestions have come from Stuart Ferguson, Ron
Minnich, Chuck McManis, Leo Schwab, Dave Navas, and many other denizens of
the net. I know I've omitted some names I shouldn't have, but a lot of
messages (of the net variety) flowed during the hectic early months.  Much
appreciation is due to all who have taken the trouble to read, consider,
and contribute to the mass of material that has accumulated. Thank you all!

                                                Pete Goodeve
                                                3012 Deakin Street #D
                                                Berkeley, Calif. 94705

                                                [[e-mail]]
                                                [...ucbvax!violet!pete]


                                %%%%%%%%%%%%%