concurrence.core – The concurrence core module

Platforms: Unix

concurrence.core.dispatch(f=None)

The main dispatch routine. This is the starting point of any Concurrence program. The dispatcher schedules tasklets until the quit() function is called or a SIGINT signal is received. As a convenience a callable f can be provided that will be run in a new Tasklet.

concurrence.core.quit(exitcode=0)

Quits the concurrence program and exit to the OS with exitcode

class concurrence.core.Tasklet

A Tasklet represents an activity that runs concurrently to other Tasklets. A Tasklet can be compared to a Thread with the main difference that Tasklets are scheduled co-operatively by the Concurrence framework as opposed to Threads, which are scheduled pre-emptively by the OS.

Only 1 Tasklet will be actually using 1 CPU at any point in time. But many Tasks may be present at the same time.

A Tasklet can become inactive (block) as soon as it performs some IO, or it explictly releases control (for instance by calling yield_()).

As soon as a Tasklet blocks, the Concurrence framework will schedule some other Tasklet to run next (in a round-robin fashion).

If a Tasklet became inactive because it needs to wait for IO, The Concurrence framework will automatically reschedule that Tasklet again as soon as that IO is complete.

Please use new() to create new tasklets

children()

Gets the set of children of this Tasklet

classmethod current()

Returns a reference to the currently running task

has_finished()

Returns whether this Tasklet has already finished or not (either with a result of with an exception).

classmethod interval(timeout, f, immediate=False, **kwargs)

Creates a new task that will execute the given callable f every timeout seconds. If immediate is True, f will be called as soon as the task is started. Otherwise, the newly started task will wait timeout seconds before calling f for the first time. See new() for a description of any further keyword arguments. Any exception that is raised by f is caught and logged but the interval task will continue running. An interval task can be stopped by calling kill() on it.

classmethod join(t, timeout=-1)

The current task will block and wait for the given task t to complete. When t is finished, this method will return its result value. If t finishes with an exception this method will raise a JoinError. Optionally a timeout in seconds may be specified. If task does not finish within timeout a TimeoutError will be raised.

classmethod join_all(tasks, timeout=-1)

The current task will block and wait for the given tasks to complete. When all tasks have finished a list of results is returned. If a task finishes with an exception the result value for that task will be an instance of JoinError. Optionally a timeout for the wait can be specified. If all tasks do not finish within timeout a TimeoutError will be raised.

classmethod join_children(timeout=-1)

A convenience method for joining all children of the current task. Behaves as join_all() where tasks is the list of children.

kill()

Raise a TaskletExit exception in the task. This will normally kill the task. Note that TaskletExit is a subclass of SystemExit and thus not a subclass of Exception. This means that if a task explicitly catches either TaskletExit or SystemExit it could prevent itself from being killed.

classmethod later(timeout, f, **kwargs)

Creates a new task that will first sleep for timeout seconds before calling f. See new() for a description of any further keyword arguments.

classmethod loop(f, **kwargs)

Creates a new task that will execute the given callable f in a loop. See new() for a description of any further keyword arguments. Any exception that is raised by f is caught and logged but the loop will continue running. A looping task can be stopped by calling kill() on it.

mailbox

The queue of messages send by other tasklets that are not yet consumed. Use receive() to get pending message for the current task. Alternatively you can use the methods of Mailbox directly.

classmethod new(f, name='', daemon=False, max_mailbox_len=None)

Creates a new task that will run callable f. The new task can optionally be named name. If no name is given a name is derived from the callable f.

The result of f will be the result of the tasklet. f may throw an exception, in which case the exception will be the result of the tasklet.

parent()

Gets the parent of this Tasklet. This method may return None if the parent is no longer there.

classmethod rate(rate, f, **kwargs)

Creates a new task that will call f rate times per second. The main difference with interval() is that this method is more accurate in calling f exactly rate times per second independent of the load generated by f and or other tasks running on the system. It does this by varying the interval on the basis of the difference between the target interval 1 / rate and the actual interval found by measuring the timing. See new() for a description of any further keyword arguments. As a convenience the current time is passed as the first parameter to f.

classmethod receive(timeout=-1)

A generator that yields the next pending Message in the mailbox of the current task. This method returns a tuple (msg, args, kwargs) for each message received. If no message is available the task blocks and waits for a message to arrive.

classmethod receive_batch(max_size, batch_timeout=-1)

A generator that yields a list of pending Message in the mailbox of the current task. The size of the list will never exceed max_size. If necessary this method waits up to batch_timeout after receiving the first message, to try to fill the list of exactly max_size entries (or it waits indefinitely if batch_timeout is not specified). In case the number of messages is less than max_size after the batch_timeout has expired, it returns a smaller list.

classmethod receiver(f, **kwargs)

Creates a new task will that will wait for messages to arrive and calls f (msg, *args, **kwargs) for each Message received. See new() for a description of any further keyword arguments.

classmethod sleep(timeout)

Blocks the current task for the given timeout in seconds.

tree(level=0)

An inorder treewalk starting at the current task and iterating over its children, grandchildren etc. this generator yields tuples (task, level).

classmethod yield_()

Calls the scheduler to cooperatively schedule some other tasks. The current class will block and some other task will continue. The current task remains runnable and after some time it will be scheduled again and this method will return. If there is no other task runnable, this method is a no-op. yield_() is used when a task is busy processing some lengthy calculation that contains no other blocking events like IO or timeouts. By calling yield_() once in a while it can prevent itself from hogging the CPU and give other tasks some change to do some work as well.

class concurrence.core.Channel

A Channel is a method for transfering control and/or communicate between Tasklets. Please note that the Channel class is basically a small wrapper around a stackless channel. It was overridden in Concurrence to provide timeouts on the send() and receive() methods.

A Tasklet can receive() from a Channel as soon as some other Tasklet will send() on the channel. If there is no sender the receiving Tasklet will block until a sender is available. If a sender and a receiver are available, the sender will pass a value to the receiver and execution will continue in the receiver (The sender will become ‘runnable’ as well, but will be placed at the end of the scheduling queue).

The reverse works the same. If there is a sender but no receiver, the sender will block until a receiver arrives. As soon as a receiver arrives, the value of the sender is passed and execution continues with the receiver (The sender will become runnable again, but will be placed at the end of the scheduling queue).

has_receiver()

Whether this Channel has any waiting receivers.

has_sender()

Whether this Channel has any waiting senders.

receive(timeout=-1)

Receive from the channel. If there is no sender, the caller will block until there is one. Optionally you can specify a timeout. If a sender does not show up within the timeout period a TimeoutError is raised. The method returns the value given by the sender.

send(value, timeout=-1)

Sends to the channel. If there is no receiver, the caller will block until there is one. If a receiver is present, the value will be passed to the receiver and execution will continue in the receiver. Optionally you can specify a timeout. If a receiver does not show up within the timeout period a TimeoutError is raised.

send_exception(*args, **kwargs)

Send an exception trough the channel instead of some value. This will immediatly raise the exception in the receiver.

class concurrence.core.Message(reply_channel=None)

classmethod call(receiver, timeout=-1)

Synchronously send the message cls to the given receiver and waits for a response. The result will be the response of the receiver. Optionally a timeout in seconds can be specified. If the receiver does not respond within the timeout period a TimeoutError is raised.

match(cls)

Checks whether this message is an instance of the given message class cls.

reply(result)

Reply to the message and return result to the caller.

classmethod send(receiver)

Asynchronously sends the message cls to the given receiver.

class concurrence.core.Mailbox(iterable=[], maxlen=None)

Every tasklet has a mailbox, a queue of messages send by other tasklets that are not yet consumed.

pop(blocking=False, timeout=-1)

Pop the last item from the end of the queue. If blocking is True, the caller will block for timeout seconds until an item becomes available.

popleft(blocking=False, timeout=-1)

Pop the first item from the start of the queue. If blocking is True, the caller will block for timeout seconds until an item becomes available.

append(x)

Append item x to the end of the queue.

appendleft(x)

Append item x to the start of the queue.

exception concurrence.core.JoinError(cause, tasklet)

A JoinError can be raised from any of the join_XXX() methods of the Tasklet class.

exception concurrence.core.TimeoutError

This exception can be raised by various methods that accept timeout parameters.