Add API docs for the scheduler
This commit is contained in:
Lance Stout
@@ -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
|
||||
Based on: 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.
|
||||
: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.
|
||||
"""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
|
||||
: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()
|
||||
|
||||
Reference in New Issue
Block a user