Axon.experimental._pprocess_support

likefile is a way to run Axon components with code that is not Axon-aware. It does this by running the scheduler and all associated microprocesses in a separate thread, and using a custom component to communicate if so desired.

Using this code

With a normal kamaelia system, you would start up a component and start running the Axon scheduler as follows, either:

from Axon.Scheduler import scheduler
component.activate()
scheduler.run.runThreads()
someOtherCode()

or simply:

component.run()
someOtherCode()

In both cases, someOtherCode() only run when the scheduler exits. What do you do if you want to (e.g.) run this alongside another external library that has the same requirement?

Well, first we start the Axon scheduler in the background as follows:

from likefile import background
background().start()

The scheduler is now actively running in the background, and you can start components on it from the foreground, in the same way as you would from inside kamaelia (don't worry, activate() is threadsafe):

component.activate()
someOtherCode()

"component" will immediately start running and processing. This is fine if it's something non-interactive like a TCP server, but what do we do if we want to interact with this component from someOtherCode?

In this case, we use 'likefile', instead of activating. This is a wrapper which sits around a component and provides a threadsafe way to interact with it, whilst it is running in the backgrounded scheduler:

from Axon.LikeFile import likefile
wrappedComponent = likefile(component)
someOtherCode()

Now, wrappedComponent is an instance of the likefile wrapper, and you can interact with "component" by calling get() on wrappedComponent, to get data from the outbox on "component", or by calling put(data) to put "data" into the inbox of "component" like so:

p = likefile( SimpleHTTPClient() )
p.put("http://google.com")
google = p.get()
p.shutdown()
print "google's homepage is", len(google), "bytes long.

for both get() and put(), there is an optional extra parameter boxname, allowing you to interact with different boxes, for example to send a message with the text "RELOAD" to a component's control inbox, you would do:

wrappedComponent.put("RELOAD", "control")
wrappedComponent.get("signal")

Finally, likefile objects have a shutdown() method that sends the usual Axon IPC shutdown messages to a wrapped component, and prevents further IO.

Advanced likefile usage

likefile has some optional extra arguments on creation, for handling custom boxes outside the "basic 4". For example, to wrap a component with inboxes called "secondary" and "tertiary" and an outbox called "debug", You would do:

p = likefile( componentMaker,
              extraInboxes = ("secondary", "tertiary"),
              extraOutboxes = "debug", )

Either strings or tuples of strings will work.

It may be the case that the component you are trying to wrap will link its own inbox/outbox/signal/control, and this will result in a BoxAlreadyLinkedToDestination exception. To stop likefile from wrapping the default 4 boxes, pass the parameter wrapDefault = False. Note that you will need to manually wrap every box you want to use, for example to wrap a component that has its own linkages for signal/control:

p = likefile( myComponent,
              wrapDefault = False,
              extraInboxes = "inbox",
              extraOutboxes = "outbox", )

Diagram of likefile's functionality

likefile is constructed from components like so:

     +----------------------------------+
     |             likefile             |
     +----------------------------------+
          |                      / \
          |                       |
      InQueues                 OutQueues
          |                       |
+---------+-----------------------+---------+
|        \ /                      |         |
|    +---------+               +--------+   |
|    |  Input  |   Shutdown    | Output |   |
|    | Wrapper | ------------> |        |   |
|    | (thread)|   Message     |Wrapper |   |
|    +---------+               +--------+   |
|         |                      / \        |
|         |                       |         |
|     Inboxes                 Outboxes      |
|         |                       |         |
|        \ /                      |         |
|    +----------------------------------+   |
|    |      the wrapped component       |   |
|    +----------------------------------+   |
|                                           |
|    +----------------------------------+   |
|    |       Some other component       |   |
|    |     that was only activated      |   |
|    +----------------------------------+   |
|                                           |
|  AXON SCHEDULED COMPONENTS                |
+-------------------------------------------+

Note 1: Threadsafeness of activate().

when a component is activated, it calls the method inherited from microprocess, which calls _addThread(self) on an appropriate scheduler. _addThread calls wakeThread, which places the request on a threadsafe queue.

Axon.experimental._pprocess_support.addBox

addBox(names, boxMap, addBox)

Add an extra wrapped box called name, using the addBox function provided (either self.addInbox or self.addOutbox), and adding it to the box mapping which is used to coordinate message routing within component wrappers.

Axon.experimental._pprocess_support.background

class background(threading.Thread)

Methods defined here

__init__(self[, slowmo][, zap])

run(self)

Axon.experimental._pprocess_support.componentWrapperInput

class componentWrapperInput(Axon.ThreadedComponent.threadedadaptivecommscomponent)

Methods defined here

__init__(self, child[, inboxes])

main(self)

pollQueue(self, whatInbox)

This method checks all the queues from the outside world, and forwards any waiting data to the child component. Returns False if we propogated a shutdown signal, true otherwise.

Axon.experimental._pprocess_support.componentWrapperOutput

class componentWrapperOutput(Axon.AdaptiveCommsComponent.AdaptiveCommsComponent)

Methods defined here

__init__(self, child, inputHandler[, outboxes])

main(self)

sendPendingOutput(self)

This method will take any outgoing data sent to us from a child component and stick it on a queue to the outside world.

Axon.experimental._pprocess_support.dummyComponent

class dummyComponent(Axon.Component.component)

Methods defined here

main(self)

Axon.experimental._pprocess_support.likefile

class likefile(object)

Methods defined here

__del__(self)

__init__(self, child[, extraInboxes][, extraOutboxes][, wrapDefault])

anyReady(self)

empty(self[, boxname])

Return True if there is no data pending collection on boxname, False otherwise.

get(self[, boxname][, blocking][, timeout])

Performs a blocking read on the queue corresponding to the named outbox on the wrapped component. raises AttributeError if the likefile is not alive. Optional parameters blocking and timeout function the same way as in Queue objects, since that is what's used under the surface.

get_nowait(self[, boxname])

Equivalent to get(boxname, False)

put(self, msg[, boxname])

Places an object on a queue which will be directed to a named inbox on the wrapped component.

qsize(self[, boxname])

Returns the approximate number of pending data items awaiting collection from boxname. Will never be smaller than the actual amount.

shutdown(self)

Sends terminatory signals to the wrapped component, and shut down the componentWrapper. will warn if the shutdown took too long to confirm in action.