Package CyberRail :: Package common :: Module communicationmanager
[hide private]
[frames] | no frames]

Module communicationmanager

source code


CommunicationManager module is a module wrapping the select / poll system calls
enabling you to have a single (or double if you adopt the non blocking mode)
threaded multiple IO management.

Via the CommunicationManager class, you will add and remove IO streams (mainly
socket, even if pipes and files also work) to the manager. This one will
dispatch your data and alerts you via callbacks when something is received.

Usage (non blocking):

    >>> ## Creating it
    >>> com = CommunicationManager(blocking = False)
    >>> com.registerLowLevelListener(allLevelListener)
    >>> com.registerHighLevelListener(allLevelListener)
    >>>
    >>> ## Enable it to listen on one port
    >>> lsid = com.listen(port=5555)
    >>>
    >>> ## Connect to another place
    >>> csid = com.connect("ip6-localhost", 5555)
    >>>
    >>> ## send something
    >>> com.sendRaw(csid, "some data")
    >>>
    >>> ## add some File Descriptors
    >>> (pin, pout) = os.pipe()
    >>> com.addFDescriptor(pout)
    >>> com.sendRaw(pout, "plop 1")
    >>> print "----->", os.read(pin, 255) ## "plop 1"
    >>> com.removeFDescriptor(pout)
    >>>
    >>>     ## Stop and close everything
    >>> com.stop()

Usage (blocking):

    >>> ## Creating it
    >>> com = CommunicationManager()
    >>> com.registerLowLevelListener(allLevelListener)
    >>> com.registerHighLevelListener(allLevelListener)
    >>>
    >>> ## Enable it to listen on one port
    >>> lsid = com.listen(port=5555)
    >>>
    >>> ## Connect to another place
    >>> csid = com.connect("ip6-localhost", 5555)
    >>>
    >>> ## Let's enter the main loop
    >>> com.main()
    >>>
    >>> ## Stop and close everything (in a callback since main is blocking)
    >>> com.stop()

    Advanced usage :

    This module support half closed connections. If you want to half close a
    connection, use the appropriate communication manager method.

    How to manage a remote read half closed connection?
    You will receive a high level "end of stream" event. In this case,
    you must hold the connection until you want to close it. As soon as you
    will unhold the connection, it will be full closed.
    You can also track the low level "PEER HALF CLOSED".

    How to manage a remote write half closed connection?
    You will receive a high level "broken pipe" event. In this case, you
    must either hold or unhold the connection (even if it is not hold).
    If you don't call one of the two, the connection will be fully closed.

    Why?

    The communication manager will cleanup all connections which are inactive.
    Connection should always poll for in data. You can disable this behavior
    by holding a connection. In this case, the connection will not be
    polled for in data but CM will keep it.

    In the case of a read half close, you will never receive data anymore
    from this connection, so POLLIN has to be cleared (keeping pollin up will
    makes poll or select returning immediatly continuously, which is wrong).
    But you can still write to this connection. So holding it will indicate
    to the CM that it shoulds keep it.

    In the case of a write half close, the default is to close the connection.
    You can either choose to continue to listen (unhold choice) or hold the
    connection for a later use (depending on the behavior of your program).
    Keeping a connection hold is a right choice only if you plan to unhold
    it later in your program.



@author: Emmanuel Coirier
@copyright: 2005-2010 Emmanuel Coirier
@license: GPL v3

Classes [hide private]
  ConnectionHandle
The Connection Handle contains the IO buffers of the associated socket.
  CommunicationManager
Manage communication between differents parts of processes, via IO.
  TimeoutsManagement
Functions [hide private]
 
convertPollState(state)
Given a value of ORed select states (POLLIN | POLLERR...), return a string with the names of the states marged with spaces ("POLLIN POLLERR").
source code
 
returnRaw(ch)
Default protoIn callback.
source code
 
returnIdentity(data)
Default protoOut callback.
source code
 
allLevelListener(event)
Basic debug callback to see what's happen'.
source code
Variables [hide private]
  pollMap = {1: 'POLLIN', 2: 'POLLPRI', 4: 'POLLOUT', 8: 'POLLER...
@undocumented
  __package__ = 'CyberRail.common'
Function Details [hide private]

returnRaw(ch)

source code 

Default protoIn callback. Return all data as string.

returnIdentity(data)

source code 

Default protoOut callback. Return all data as string.


Variables Details [hide private]

pollMap

@undocumented

Value:
{1: 'POLLIN',
 2: 'POLLPRI',
 4: 'POLLOUT',
 8: 'POLLERR',
 16: 'POLLHUP',
 32: 'POLLNVAL'}