Job: + whenStarted, whenFinished callbacks, now with additional job argument; let Scheduler.schedule() return the real startTime (may be used as jobId)

git-svn-id: svn://svn.cy55.de/Zope3/src/loops/trunk@1917 fd906abe-77d9-0310-91a1-e0d9ade77398

agent/README.txt

@@ -129,6 +129,7 @@ How does this work?
 -------------------
 
   >>> from time import time
+
   >>> from loops.agent.schedule import Job
   >>> class TestJob(Job):
   ...     def execute(self):
@@ -137,6 +138,10 @@ How does this work?
   ...         return d
 
   >>> scheduler = agent.scheduler
+
+The ``schedule()`` method accepts the start time as a second argument,
+if not present use the current time, i.e. start the job immediately.
+
   >>> startTime = scheduler.schedule(TestJob())
 
   >>> tester.iterate()

agent/interfaces.py

@@ -43,9 +43,14 @@ class IScheduler(Interface):
     logger = Attribute('Logger instance to be used for recording '
                        'job execution and execution results.')
 
-    def schedule(job, startTime):
+    def schedule(job, startTime=None):
         """ Register the job given for execution at the intended start
-            date/time and return the job.
+            date/time (an integer timestamp) and return the job.
+
+            If the start time is not given schedulethe job for immediate
+            start. Return the start time with which the job has been
+            scheduled - this may be different from the start time
+            supplied.
         """
 
     def getJobsToExecute(startTime=None):