summaryrefslogtreecommitdiff
path: root/sleekxmpp
diff options
context:
space:
mode:
authorLance Stout <lancestout@gmail.com>2011-12-04 16:43:05 -0800
committerLance Stout <lancestout@gmail.com>2011-12-04 16:43:05 -0800
commita85891c611aaacbd3fdd7d4a2cff89e22409db6d (patch)
tree2268eda858eead3eb68b37a6b7eac46b97288b87 /sleekxmpp
parent2586fdffda9dac5ee56664c74e71bd54ae47ee18 (diff)
downloadslixmpp-a85891c611aaacbd3fdd7d4a2cff89e22409db6d.tar.gz
slixmpp-a85891c611aaacbd3fdd7d4a2cff89e22409db6d.tar.bz2
slixmpp-a85891c611aaacbd3fdd7d4a2cff89e22409db6d.tar.xz
slixmpp-a85891c611aaacbd3fdd7d4a2cff89e22409db6d.zip
Add API docs for the scheduler
Diffstat (limited to 'sleekxmpp')
-rw-r--r--sleekxmpp/xmlstream/scheduler.py148
1 files changed, 70 insertions, 78 deletions
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()