github/SleekXMPP
1
0
Fork 0
mirror of https://github.com/correl/SleekXMPP.git synced 2024-11-23 19:19:53 +00:00
Code Issues Projects Releases Packages Wiki Activity

Add API docs for the scheduler

Browse source
This commit is contained in:
Lance Stout 2011-12-04 16:43:05 -08:00
parent 2586fdffda
commit a85891c611
3 changed files with 80 additions and 76 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
docs/api/xmlstream/scheduler.rst Normal file
View file

@ -0,0 +1,11 @@
=========
Scheduler
=========
.. module:: sleekxmpp.xmlstream.scheduler
.. autoclass:: Task
:members:
.. autoclass:: Scheduler
:members:

1
docs/index.rst
View file

@ -116,6 +116,7 @@ API Reference
api/xmlstream/stanzabase api/xmlstream/stanzabase
api/xmlstream/handler api/xmlstream/handler
api/xmlstream/matcher api/xmlstream/matcher
api/xmlstream/scheduler
api/xmlstream/tostring api/xmlstream/tostring
api/xmlstream/filesocket api/xmlstream/filesocket

144
sleekxmpp/xmlstream/scheduler.py
View file

@ -1,9 +1,15 @@
# -*- coding: utf-8 -*-
""" """
SleekXMPP: The Sleek XMPP Library sleekxmpp.xmlstream.scheduler
Copyright (C) 2010 Nathanael C. Fritz ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This file is part of SleekXMPP.
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 import time
@ -24,50 +30,47 @@ class Task(object):
A scheduled task that will be executed by the scheduler A scheduled task that will be executed by the scheduler
after a given time interval has passed. after a given time interval has passed.
Attributes: :param string name: The name of the task.
name -- The name of the task. :param int seconds: The number of seconds to wait before executing.
seconds -- The number of seconds to wait before executing. :param callback: The function to execute.
callback -- The function to execute. :param tuple args: The arguments to pass to the callback.
args -- The arguments to pass to the callback. :param dict kwargs: The keyword arguments to pass to the callback.
kwargs -- The keyword arguments to pass to the callback. :param bool repeat: Indicates if the task should repeat.
repeat -- Indicates if the task should repeat. Defaults to ``False``.
Defaults to False. :param pointer: A pointer to an event queue for queuing callback
qpointer -- A pointer to an event queue for queuing callback
execution instead of executing immediately. 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, def __init__(self, name, seconds, callback, args=None,
kwargs=None, repeat=False, qpointer=None): kwargs=None, repeat=False, qpointer=None):
""" #: The name of the task.
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.
"""
self.name = name self.name = name
#: The number of seconds to wait before executing.
self.seconds = seconds self.seconds = seconds
#: The function to execute once enough time has passed.
self.callback = callback self.callback = callback
#: The arguments to pass to :attr:`callback`.
self.args = args or tuple() self.args = args or tuple()
#: The keyword arguments to pass to :attr:`callback`.
self.kwargs = kwargs or {} self.kwargs = kwargs or {}
#: Indicates if the task should repeat after executing,
#: using the same :attr:`seconds` delay.
self.repeat = repeat self.repeat = repeat
#: The time when the task should execute next.
self.next = time.time() + self.seconds 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 self.qpointer = qpointer
def run(self): 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; If an event queue was supplied, place the callback in the queue;
otherwise, execute the callback immediately. otherwise, execute the callback immediately.
@ -81,9 +84,7 @@ class Task(object):
return self.repeat return self.repeat
def reset(self): 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 self.next = time.time() + self.seconds
@ -93,46 +94,41 @@ class Scheduler(object):
A threaded scheduler that allows for updates mid-execution unlike the A threaded scheduler that allows for updates mid-execution unlike the
scheduler in the standard library. 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: :param parentstop: An :class:`~threading.Event` to signal stopping
addq -- A queue storing added tasks. the scheduler.
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.
""" """
def __init__(self, parentstop=None): def __init__(self, parentstop=None):
""" #: A queue for storing tasks
Create a new scheduler.
Arguments:
parentstop -- A threading event indicating if the main process has
been stopped.
"""
self.addq = queue.Queue() self.addq = queue.Queue()
#: A list of tasks in order of execution time.
self.schedule = [] self.schedule = []
#: If running in threaded mode, this will be the thread processing
#: the schedule.
self.thread = None self.thread = None
#: A flag indicating that the scheduler is running.
self.run = False self.run = False
#: An :class:`~threading.Event` instance for signalling to stop
#: the scheduler.
self.stop = parentstop self.stop = parentstop
#: Lock for accessing the task queue.
self.schedule_lock = threading.RLock() self.schedule_lock = threading.RLock()
def process(self, threaded=True): def process(self, threaded=True):
""" """Begin accepting and processing scheduled tasks.
Begin accepting and processing scheduled tasks.
Arguments: :param bool threaded: Indicates if the scheduler should execute
threaded -- Indicates if the scheduler should execute in its own in its own thread. Defaults to ``True``.
thread. Defaults to True.
""" """
if threaded: if threaded:
self.thread = threading.Thread(name='sheduler_process', self.thread = threading.Thread(name='scheduler_process',
target=self._process) target=self._process)
self.thread.start() self.thread.start()
else: else:
@ -183,18 +179,16 @@ class Scheduler(object):
def add(self, name, seconds, callback, args=None, def add(self, name, seconds, callback, args=None,
kwargs=None, repeat=False, qpointer=None): kwargs=None, repeat=False, qpointer=None):
""" """Schedule a new task.
Schedule a new task.
Arguments: :param string name: The name of the task.
name -- The name of the task. :param int seconds: The number of seconds to wait before executing.
seconds -- The number of seconds to wait before executing. :param callback: The function to execute.
callback -- The function to execute. :param tuple args: The arguments to pass to the callback.
args -- The arguments to pass to the callback. :param dict kwargs: The keyword arguments to pass to the callback.
kwargs -- The keyword arguments to pass to the callback. :param bool repeat: Indicates if the task should repeat.
repeat -- Indicates if the task should repeat. Defaults to ``False``.
Defaults to False. :param pointer: A pointer to an event queue for queuing callback
qpointer -- A pointer to an event queue for queuing callback
execution instead of executing immediately. execution instead of executing immediately.
""" """
try: try:
@ -211,12 +205,10 @@ class Scheduler(object):
self.schedule_lock.release() self.schedule_lock.release()
def remove(self, name): def remove(self, name):
""" """Remove a scheduled task ahead of schedule, and without
Remove a scheduled task ahead of schedule, and without
executing it. executing it.
Arguments: :param string name: The name of the task to remove.
name -- The name of the task to remove.
""" """
try: try:
self.schedule_lock.acquire() self.schedule_lock.acquire()