Axon.Handle

Still Experimental

This code is currently experimental - we'd welcome reports of any issues you may encounter when using this code.

Example Usage

Here, Axon/Kamaelia is used to connect to a server then receive text, chunking it into individual lines. This is done by using Axon in the background (since other code in this hypothetical system is not Axon based).

NOTE: To see how this could be done without using Axon.Handle, see the examples in the documentation for Axon.background.

1. We create a background object and call its start() method:

   from Axon.background import background
   
   background().start()
   

2. We create and activate our Kamaelia pipeline of components, wrapped in an instance of the Handle class:

   from Axon.Handle import Handle
   from Kamaelia.Chassis.Pipeline import Pipeline
   from Kamaelia.Internet.TCPClient import TCPClient
   from Kamaelia.Visualisation.PhysicsGraph import chunks_to_lines
   
   queue = Queue()
   
   connection = Handle(
       Pipeline(
           TCPClient("my.server.com", 1234),
           chunks_to_lines()
       )
   ).activate()
   

We can now fetch items of data when they arrive, using the Handle, from the "outbox" outbox of the pipeline:

from Queue import Empty

while 1:
   try:
       received_line = connection.get("outbox")
       print "Received line:", received_line
   except Empty:
       # no data yet
       time.sleep(0.1)

We can also send data, back to the server, by sending it to the "inbox" inbox of the pipeline:

connection.put("Bytes to send to server\n", "inbox")

Behaviour

Handle is a threaded component. It does not have the standard inboxes ("inbox" and "control") or standard outboxes ("outbox" and "signal"). The only way to communicate with Handle is via its get() and put() methods.

Instantiate Handle, passing it a component to wrap. Upon activation, Handle automatically wires inboxes and outboxes of its own to the "inbox" and "control" inboxes and "outbox" and "signal" outboxes of the component it is wrapping. Handle then activates the wrapped component.

To send data to the wrapped component's "inbox" or "control" inboxes, call the put() method, specifying, as arguments, the item of data and the name of the inbox it is destined for. The data is queued and sent at the next opportunity.

To retrieve data sent out by the wrapped component's "outbox" or "signal" outboxes, call the get() method, specifying, as an argument, the name of the outbox in question. This method is non blocking - if there is data waiting, then the oldest item of data is returned, otherwise a Queue.Empty exception is immediately thrown.

When the wrapped component terminates, Handle will immediately terminate. Handle does not respond to shutdown messages received from the wrapped component. Handle cannot be sent shutdown messages since it has no "control" inbox on which to receive them.

Limitations

Design rationale and history

This component is the successor to the earlier "likefile" component. Likefile suffered from some design issues that resulted in occassional race conditions.

We dropped the name "LikeFile" since whilst it derives from the concept of a file handle, it doesn't use the same API as file() for some good reasons we'll come back to.

A file handle is an opaque thing that you can .write() data to, and .read() data from. This is a very simple concept and belies a huge amount of parallel activity happening concurrently to your application. The file system is taking your data and typically buffering it into blocks. Those blocks then may need padding, and depending on the file system, may actually be written immediately to the end of a cyclone buffer in a journal with some write operations. Then periodically those buffers get flushed to the actual disk.

Based on the fact that file handles are a very natural thing for people to work with, based on their ubiquity, and the fact that it masks the fact you're accessing a concurrent system from a linear one, that's why we've taken this approach for integrating Kamaelia components (which are naturally parallel) with non-Kamaelia code, which is typically not parallel.

For simplicity of implementation, initially the implementation of Handle supports only the equivalent of non-blocking file handles. This has two implications:

• Reading data from a Handle may fail, since there may not be any ready yet. This is chosen in preference to a blocking operation
• Writing data to a Handle may also fail, since the component may not actually be ready to receive data from us.

class Handle(Axon.ThreadedComponent.threadedcomponent)