cs.resources 20190103

resourcing related classes and functions

Resource management classes and functions.

Class ClosedError

MRO: builtins.Exception, builtins.BaseException
Exception for operations invalid when something is closed.

Class MultiOpen

MRO: MultiOpenMixin, cs.obj.O
Context manager class that manages a single open/close object using a MultiOpenMixin.

Class MultiOpenMixin

MRO: cs.obj.O
A mixin to count open and close calls, and to call .startup on the first .open and to call .shutdown on the last .close.

Recommended subclass implementations do as little as possible during init, and do almost all setup during startup so that the class may perform multiple startup/shutdown iterations.

If used as a context manager calls open()/close() from enter() and exit().

Multithread safe.

This mixin defines ._lock = RLock(); subclasses need not bother, but may supply their own lock.

Classes using this mixin need to define .startup and .shutdown.

Function not_closed(func)

Decorator to wrap methods of objects with a .closed property which should raise when self.closed.

Class Pool

MRO: cs.obj.O
A generic pool of objects on the premise that reuse is cheaper than recreation.

All the pool objects must be suitable for use, so the new_object callable will typically be a closure. For example, here is the init for a per-thread AWS Bucket using a distinct Session:

def __init__(self, bucket_name):
    Pool.__init__(self, lambda: boto3.session.Session().resource('s3').Bucket(bucket_name)

Class RunState

A class to track a running task whose cancellation may be requested.

Its purpose is twofold, to provide easily queriable state around tasks which can start and stop, and to provide control methods to pronounce that a task has started, should stop (cancel) and has stopped (stop).

A RunState can be used a a context manager, with the enter and exit methods calling .start and .stop respectively.

Monitor or daemon processes can poll the RunState to see when they should terminate, and may also manage the overall state easily using a context manager. Example:

def monitor(self):
    with self.runstate:
        while not self.runstate.cancelled:
            ... main loop body here ...

A RunState has three main methods:

• .start(): set .running and clear .cancelled
• .cancel(): set .cancelled
• .stop(): clear .running

A RunState has the following properties:

• cancelled: true if .cancel has been called.
• running: true if the task is running. Assigning a true value to it also sets .start_time to now. Assigning a false value to it also sets .stop_time to now.
• start_time: the time .running was last set to true.
• stop_time: the time .running was last set to false.
• run_time: max(0, .stop_time - .start_time)
• stopped: true if the task is not running.
• stopping: true if the task is running but has been cancelled.
• notify_start: a set of callables called with the RunState instance to be called whenever .running becomes true.
• notify_end: a set of callables called with the RunState instance to be called whenever .running becomes false.
• notify_cancel: a set of callables called with the RunState instance to be called whenever .cancel is called.

Class RunStateMixin

Mixin to provide convenient access to a RunState. Provides: .runstate, .cancelled, .running, .stopping, .stopped.