#----------------------------------------------------------------------------#
#                                                                            #
#   pIPC is (c) 2000-2003 Fionn Behrens <fi@nn.org> and may be distributed   #
#    and used freely under the licensing terms of the GNU Public License     #
#                             (http://www.fsf.org/)                          #
#                                                                            #
#   For further information, updates and documentation of IPC.py check out:  #
#                         http://fionn.de/software/pIPC/                     #
#                                                                            #
#   If you use this software in a project that is deployed in professional   #
#  environments and/or on a large scale, you should feel obliged to send an  #
# EMail to the author (see top for address), telling him about your project. #
#  Donations and chocolate are always welcome but, certainly, not mandatory. #
#                                                                            #
#----------------------------------------------------------------------------#


The pIPC module implements the classes Pipe, PipeEnd and PipeServer, which
can be used for hassle-free, queued inter-process communications (IPC).

Example Usage:

import pIPC

pipe = pIPC.Pipe()

start_new_thread(my_func,(pipe,my_args,...))

each process or thread can now (EQALLY!) use the pipe, f.e.:

r,w,x = select([pipe],[],[],1)

if r != []:
  if r[0] != pipe:
    raise IOError, "unknown file IO in select()" # whatever... shouldnt happen
  data = pipe.read()    # This data is from the other thread, it must
                        # have called pipe.write(data)
  if len(pipe) > 0:           # If there are more messages than just one, you
    moredata = pipe.pending() # can retrieve an array of all pending messages
else:                         # from the pipe with the pending() method.
  pipe.write("Got no data! Are you sleeping?")  # Will be readable by the other
                                                # thread, using pipe.read()

Or whatever. The pipe class will take care of everything, including queueing
of multiple messages until pending messages are completely read.

If you want to do IPC with completely separate processes (i.e. spawn()ed) you
will have to use named pipes aka "fifo"s. Use them almost exactly like above
standard pipes, just use

pipe = pIPC.Pipe("mypipe")   # Use your favorite unique name instead of mypipe

in BOTH processes involved. After that you can use them in just the same way
that is shown above. The fifos will be unlinked from /tmp when both sides have
opened them and remain invisble.

But that is not all. If you want to do IPC between two separate computers
through the net, just use

pipe = pIPC.Pipe("remote_host_name", port [, timeout])

on both computers involved to get your pIPC message interface as usual.
Whichever side is first to do so will open the port and the other side
will connect to it. Optionally you can specify a how long the first
link partner will wait for the second one to connect (timeout).

If you need server functionality on one side, you can use

pserv = PipeServer(port)

where port is the number of the port of the server. Put pserv into a select
clause and every time it triggers just get a newly connected Pipe Object via

pipe = pserv.accept()

CAVEATS:

* Thoroughly tested only with linux threads (pipes) and processes (fifos)

* version 0.9.5 and up dont work with python 1.5.2 anymore.

* Communication is strictly two-way. No "one sender and two recipients" method.
  Just use two Pipe()s for stuff like that (see PipeServer).

* Only standard Pipes are reusable. Named pipes and Network pipes will have
  to be disposed whenever the connection has been interrupted. (just make
  yourself a new pair'o'Pipe()s then, its free!)

* The only thing that you will have to take care of is that if you end a thread
  and you want to re-use its end of a pipe for another process, the exiting
  thread will have to call pipe.disconnect() before it ends. The other end of
  the pipe will get a message containing the string "BYE" (plus any string you
  can submit as an argument as disconnect(string)). Sending any further
  message after disconnect() will reconnect the pipe to the calling process.

* Messages are separated internally using the sequence "<E0X\0>". Although it
  is extremely improbable that this sequence occurs in any data stream,
  it may cause unexpected behaviour, should this ever happen.

* If you have lots of data sent, use select() or do pipe.flush() regularly in
  the receiving process, or messages will overflow the posix pipe buffers and
  cause write errors on the sending thread's side. pipe.flush() will NOT
  delete messages, just flush the "physical" posix, named or network pipe and 
  store the data for later retrieval via pipe.read()

* Always call the close() method of a pipe if you do not plan to use it any more
  or you might run out of file descriptors quickly.

* pIPC is still in development. Internal structures may change in future
  releases, although the Pipe Class API in its current form will probably stay
  as it is or be expanded, but not changed. Use of other internal structures
  is depreciated at the moment.

  Send bug reports and enhancement requests/patches to pIPC@software.fionn.de
  If this module made your day, ask for my adress and send chocolate. ;-)

Fionn Behrens