diff options
| -rw-r--r-- | docs/api/xmlstream/scheduler.rst | 11 | ||||
| -rw-r--r-- | docs/index.rst | 1 | ||||
| -rw-r--r-- | sleekxmpp/xmlstream/scheduler.py | 148 |
3 files changed, 82 insertions, 78 deletions
diff --git a/docs/api/xmlstream/scheduler.rst b/docs/api/xmlstream/scheduler.rst new file mode 100644 index 00000000..ff91701e --- /dev/null +++ b/docs/api/xmlstream/scheduler.rst @@ -0,0 +1,11 @@ +========= +Scheduler +========= + +.. module:: sleekxmpp.xmlstream.scheduler + +.. autoclass:: Task + :members: + +.. autoclass:: Scheduler + :members: diff --git a/docs/index.rst b/docs/index.rst index 5d2577d2..4b7a006c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -116,6 +116,7 @@ API Reference api/xmlstream/stanzabase api/xmlstream/handler api/xmlstream/matcher + api/xmlstream/scheduler api/xmlstream/tostring api/xmlstream/filesocket diff --git a/sleekxmpp/xmlstream/scheduler.py b/sleekxmpp/xmlstream/scheduler.py index 45d24272..4a6f073f 100644 --- a/sleekxmpp/xmlstream/scheduler.py +++ b/sleekxmpp/xmlstream/scheduler.py @@ -1,9 +1,15 @@ +# -*- coding: utf-8 -*- """ - SleekXMPP: The Sleek XMPP Library - Copyright (C) 2010 Nathanael C. Fritz - This file is part of SleekXMPP. + sleekxmpp.xmlstream.scheduler + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - See the file LICENSE for copying permission. + This module provides a task scheduler that works better + with SleekXMPP's threading usage than the stock version. + + Part of SleekXMPP: The Sleek XMPP Library + + :copyright: (c) 2011 Nathanael C. Fritz + :license: MIT, see LICENSE for more details """ import time @@ -24,50 +30,47 @@ class Task(object): A scheduled task that will be executed by the scheduler after a given time interval has passed. - Attributes: - name -- The name of the task. - seconds -- The number of seconds to wait before executing. - callback -- The function to execute. - args -- The arguments to pass to the callback. - kwargs -- The keyword arguments to pass to the callback. - repeat -- Indicates if the task should repeat. - Defaults to False. - qpointer -- A pointer to an event queue for queuing callback + :param string name: The name of the task. + :param int seconds: The number of seconds to wait before executing. + :param callback: The function to execute. + :param tuple args: The arguments to pass to the callback. + :param dict kwargs: The keyword arguments to pass to the callback. + :param bool repeat: Indicates if the task should repeat. + Defaults to ``False``. + :param pointer: A pointer to an event queue for queuing callback execution instead of executing immediately. - - Methods: - run -- Either queue or execute the callback. - reset -- Reset the task's timer. """ def __init__(self, name, seconds, callback, args=None, kwargs=None, repeat=False, qpointer=None): - """ - Create a new task. - - Arguments: - name -- The name of the task. - seconds -- The number of seconds to wait before executing. - callback -- The function to execute. - args -- The arguments to pass to the callback. - kwargs -- The keyword arguments to pass to the callback. - repeat -- Indicates if the task should repeat. - Defaults to False. - qpointer -- A pointer to an event queue for queuing callback - execution instead of executing immediately. - """ + #: The name of the task. self.name = name + + #: The number of seconds to wait before executing. self.seconds = seconds + + #: The function to execute once enough time has passed. self.callback = callback + + #: The arguments to pass to :attr:`callback`. self.args = args or tuple() + + #: The keyword arguments to pass to :attr:`callback`. self.kwargs = kwargs or {} + + #: Indicates if the task should repeat after executing, + #: using the same :attr:`seconds` delay. self.repeat = repeat + + #: The time when the task should execute next. self.next = time.time() + self.seconds + + #: The main event queue, which allows for callbacks to + #: be queued for execution instead of executing immediately. self.qpointer = qpointer def run(self): - """ - Execute the task's callback. + """Execute the task's callback. If an event queue was supplied, place the callback in the queue; otherwise, execute the callback immediately. @@ -81,9 +84,7 @@ class Task(object): return self.repeat def reset(self): - """ - Reset the task's timer so that it will repeat. - """ + """Reset the task's timer so that it will repeat.""" self.next = time.time() + self.seconds @@ -93,46 +94,41 @@ class Scheduler(object): A threaded scheduler that allows for updates mid-execution unlike the scheduler in the standard library. - http://docs.python.org/library/sched.html#module-sched - - Attributes: - addq -- A queue storing added tasks. - schedule -- A list of tasks in order of execution times. - thread -- If threaded, the thread processing the schedule. - run -- Indicates if the scheduler is running. - stop -- Threading event indicating if the main process - has been stopped. - Methods: - add -- Add a new task to the schedule. - process -- Process and schedule tasks. - quit -- Stop the scheduler. + Based on: http://docs.python.org/library/sched.html#module-sched + + :param parentstop: An :class:`~threading.Event` to signal stopping + the scheduler. """ def __init__(self, parentstop=None): - """ - Create a new scheduler. - - Arguments: - parentstop -- A threading event indicating if the main process has - been stopped. - """ + #: A queue for storing tasks self.addq = queue.Queue() + + #: A list of tasks in order of execution time. self.schedule = [] + + #: If running in threaded mode, this will be the thread processing + #: the schedule. self.thread = None + + #: A flag indicating that the scheduler is running. self.run = False + + #: An :class:`~threading.Event` instance for signalling to stop + #: the scheduler. self.stop = parentstop + + #: Lock for accessing the task queue. self.schedule_lock = threading.RLock() def process(self, threaded=True): - """ - Begin accepting and processing scheduled tasks. + """Begin accepting and processing scheduled tasks. - Arguments: - threaded -- Indicates if the scheduler should execute in its own - thread. Defaults to True. + :param bool threaded: Indicates if the scheduler should execute + in its own thread. Defaults to ``True``. """ if threaded: - self.thread = threading.Thread(name='sheduler_process', + self.thread = threading.Thread(name='scheduler_process', target=self._process) self.thread.start() else: @@ -183,18 +179,16 @@ class Scheduler(object): def add(self, name, seconds, callback, args=None, kwargs=None, repeat=False, qpointer=None): - """ - Schedule a new task. - - Arguments: - name -- The name of the task. - seconds -- The number of seconds to wait before executing. - callback -- The function to execute. - args -- The arguments to pass to the callback. - kwargs -- The keyword arguments to pass to the callback. - repeat -- Indicates if the task should repeat. - Defaults to False. - qpointer -- A pointer to an event queue for queuing callback + """Schedule a new task. + + :param string name: The name of the task. + :param int seconds: The number of seconds to wait before executing. + :param callback: The function to execute. + :param tuple args: The arguments to pass to the callback. + :param dict kwargs: The keyword arguments to pass to the callback. + :param bool repeat: Indicates if the task should repeat. + Defaults to ``False``. + :param pointer: A pointer to an event queue for queuing callback execution instead of executing immediately. """ try: @@ -211,12 +205,10 @@ class Scheduler(object): self.schedule_lock.release() def remove(self, name): - """ - Remove a scheduled task ahead of schedule, and without + """Remove a scheduled task ahead of schedule, and without executing it. - Arguments: - name -- The name of the task to remove. + :param string name: The name of the task to remove. """ try: self.schedule_lock.acquire() |