March 2024 - This site, and Kamaelia are being updated. There is significant work needed, and PRs are welcome.

Axon.ThreadedComponent.threadedcomponent

For examples and more explanations, see the module level docs.


class threadedcomponent(Axon.Component.component)

threadedcomponent([queuelengths]) -> new threadedcomponent

Base class for a version of an Axon component that runs main() in a separate thread (meaning it can, for example, block). Subclass to make your own.

Internal queues buffer data between the thread and the Axon inboxes and outboxes of the component. Set the default queue length at initialisation (default=1000).

A simple example:

class IncrementByN(Axon.ThreadedComponent.threadedcomponent):

    Inboxes = { "inbox" : "Send numbers here",
                "control" : "NOT USED",
              }
    Outboxes = { "outbox" : "Incremented numbers come out here",
                 "signal" : "NOT USED",
               }

    def __init__(self, N):
        super(IncrementByN,self).__init__()
        self.n = N

    def main(self):
        while 1:
            while self.dataReady("inbox"):
                value = self.recv("inbox")
                value = value + self.n
                self.send(value,"outbox")

            if not self.anyReady():
                self.pause()

Methods defined here

__init__(self, queuelengths, **argd)

_do_threadsafe(self, cmd, argL, argD)

Internal method for ensuring a method call takes place in the main scheduler's thread.

_handlemessagefromthread(self, msg)

Unpacks a message containing a request to run a method of the form (objectToCall, argList, argDict) then calls it and places the result in the axontothreadqueue queue.

Used to execute methods on behalf of the separate thread. Results are returned to it via the return queue.

_localmain(self)

Do not overide this unless you reimplement the pass through of the boxes to the threads, and state management.

_threadmain(self)

Exception trapping wrapper for main().

Runs in the separate thread. Catches any raised exceptions and attempts to pass them back to _localmain() to be re-raised.

activate(self[, Scheduler][, Tracker][, mainmethod])

Call to activate this microprocess, so it can start to be executed by a scheduler. Usual usage is to simply call x.activate().

See Axon.Microprocess.microprocess.activate() for more info.

closeDownComponent(self)

Stub method. This method is designed to be overridden.

dataReady(self[, boxname])

Returns true if data is available in the requested inbox.

Used by the main() method of a component to check an inbox for ready data.

Call this method to periodically check whether you've been sent any messages to deal with!

You are unlikely to want to override this method.

forwardInboxToThread(self, box)

initialiseComponent(self)

Stub method. This method is designed to be overridden.

link(self, source, sink[, passthrough])

Creates a linkage from one inbox/outbox to another.

-- source - a tuple (component, boxname) of where the link should start from -- sink - a tuple (component, boxname) of where the link should go to

Other optional arguments:

  • passthrough=0 - (the default) link goes from an outbox to an inbox
  • passthrough=1 - the link goes from an inbox to another inbox
  • passthrough=2 - the link goes from an outbox to another outbox

See Axon.Postoffice.link(...) for more information.

main(self)

Override this method, writing your own main thread of control as an ordinary method. When the component is activated and the scheduler is running, this what gets executed.

Write it as an ordinary method. Because it is run in a separate thread, it can block.

If you do not override it, then a default main method exists instead that will:

  1. Call self.initialiseComponent()
  2. Loop forever calling self.mainBody() repeatedly until mainBody() returns a False/zero result.
  3. Call self.closeDownComponent()

mainBody(self)

Stub method. This method is designed to be overridden.

pause(self[, timeout])

Pauses the thread and blocks - does not return until the something happens to re-awake it, or until it times out (if the optional timeout is specified)

Must only be called from within the main() method - ie. from within the separate thread.

Keyword arguments:

  • timeout -- Optional. None, or the number of seconds after which this call should unblock itself (default=None)

recv(self[, boxname])

returns the first piece of data in the requested inbox.

Used by the main() method to recieve a message from the outside world. All comms goes via a named box/input queue

You will want to call this method to actually recieve messages you've been sent. You will want to check for new messages using dataReady first though.

You are unlikely to want to override this method.

send(self, message[, boxname])

appends message to the requested outbox.

Used by the main() method to send a message to the outside world. All comms goes via a named box/output queue

You will want to call this method to send messages.

Raises Axon.AxonExceptions.noSpaceInBox if this outbox is linked to a destination inbox that is full, or if your component is producing messages faster than Axon can pass them on.

You are unlikely to want to override this method.

sync(self)

Call this from main() to synchronise with the main scheduler's thread.

You may wish to do this to throttle your component's behaviour This is akin to posix.sched_yield or shoving extra "yield" statements into a component's generator.

unlink(self[, thecomponent][, thelinkage])

Destroys all linkages to/from the specified component or destroys the specific linkage specified.

Only destroys linkage(s) that were created by this component itself.

Keyword arguments:

  • thecomponent -- None or a component object
  • thelinakge -- None or the linkage to remove

Methods inherited from Axon.Component.component :

Methods inherited from Axon.Microprocess.microprocess :

Feedback

Got a problem with the documentation? Something unclear that could be clearer? Want to help improve it? Constructive criticism is very welcome - especially if you can suggest a better rewording!

Please leave you feedback here in reply to the documentation thread in the Kamaelia blog.

-- Automatic documentation generator, 09 Dec 2009 at 04:00:25 UTC/GMT