# HG changeset patch
# User Jan Vrany <jan.vrany@fit.cvut.cz>
# Date 1312402880 -7200
# Node ID 44d00fea6ee0c5aff472ba83c1f66a157a9af5e1
# Parent  55c6a3887ebfb21ea47ae421111172ea2ea24eb7
Added documentation and examples

diff -r 55c6a3887ebf -r 44d00fea6ee0 BackgroundJob.st
--- a/BackgroundJob.st	Wed Aug 03 22:21:08 2011 +0200
+++ b/BackgroundJob.st	Wed Aug 03 22:21:20 2011 +0200
@@ -64,8 +64,63 @@
 
 documentation
 "
-    An entry in a background-job-processing (aka batch) system.
-    The processor is elsewhere.
+    A BackgroundJob is a helper class for any kind of background
+    processing. Possible uses include (but not limited to): 
+    copying files, syntax higlighting, live searching, autosave, etc.
+
+    A task to be processed in a background is given to instances
+    in a form of a block or a message send. The background task must 
+    be then started by sending a #start message to the instance of 
+    the job. A job may be restarted any time by sending #restart or
+    terminated by sending a #stop. Sending #start to already started
+    job does nothing.
+
+    Implementation note: 
+    The the task is actually processed in a separate, exclusive    
+    the worker thread, so an explicit synchronization have to
+    be done iff the task accesses possibly shared data. 
+    The worker exists only iff the job is actually running. When 
+    the task is finished, worker thread terminates.
+
+    [author:]
+        Jan Vrany <jan.vrany@fit.cvut.cz>
+
+    [instance variables:]
+        name    <String|nil>            A user friendly name of a job,
+                                        useful for identifing job's thread in
+                                        process list.
+        job     <Block|MessageSend>     A task to perform in background.
+        priority<Integer>               A priority of worker thread. Defaults to
+                                        Processor userBackgroundPriority.
+        thread  <Process|nil>           The worker thread
+        running <Boolean>               Boolean value indicating whether
+                                        tasks already started or not.
+
+    [see also:]
+        BackgroundQueueProcessingJob
+        Tools::CodeHighlightingService (uses this class)
+    
+    
+
+"
+!
+
+examples
+"
+    | job text |
+    job :=  BackgroundJob named: 'example job' on:[
+                Delay waitForSeconds: 3.
+                Transcript showCR:'One guy said: ', text
+            ].
+    text := 'Hello world'.
+    job restart.
+    Delay waitForSeconds: 5.
+    text := 'Ahoj Svete!!'.
+    job restart.
+    Delay waitForSeconds: 1.
+    text := 'Haya, I''m talking fast, you should not see the czech greeting'.
+    job restart.
+
 "
 ! !
 
@@ -105,7 +160,13 @@
 !
 
 job:aBlockOrMessageSend
+
+    "Sets the job to be done. The job is sent
+    #value from the worker thread once started"
+
     job := aBlockOrMessageSend.
+
+    "Modified (comment): / 03-08-2011 / 21:02:41 / Jan Vrany <jan.vrany@fit.cvut.cz>"
 !
 
 name
@@ -123,12 +184,12 @@
 !
 
 priority:anInteger
-    "Set the priority of a job thread"
+    "Set the priority of a worker thread"
 
     priority := anInteger.
 
-    "Modified (comment): / 29-07-2011 / 10:54:15 / Jan Vrany <jan.vrany@fit.cvut.cz>"
     "Modified (format): / 03-08-2011 / 16:42:45 / cg"
+    "Modified (comment): / 03-08-2011 / 21:01:40 / Jan Vrany <jan.vrany@fit.cvut.cz>"
 ! !
 
 !BackgroundJob methodsFor:'initialization'!
@@ -182,6 +243,7 @@
 !BackgroundJob methodsFor:'start & stop'!
 
 restart
+
     running ifTrue:[
         self stop.
     ].
@@ -189,6 +251,7 @@
 
     "Created: / 28-04-2011 / 20:31:41 / Jan Vrany <jan.vrany@fit.cvut.cz>"
     "Modified (format): / 03-08-2011 / 16:42:39 / cg"
+    "Modified (comment): / 03-08-2011 / 21:03:21 / Jan Vrany <jan.vrany@fit.cvut.cz>"
 !
 
 start
@@ -235,11 +298,11 @@
 !BackgroundJob class methodsFor:'documentation'!
 
 version
-    ^ '$Header: /cvs/stx/stx/libbasic2/BackgroundJob.st,v 1.6 2011-08-03 14:46:18 cg Exp $'
+    ^ '$Header: /cvs/stx/stx/libbasic2/BackgroundJob.st,v 1.7 2011-08-03 20:21:20 vrany Exp $'
 !
 
 version_CVS
-    ^ '$Header: /cvs/stx/stx/libbasic2/BackgroundJob.st,v 1.6 2011-08-03 14:46:18 cg Exp $'
+    ^ '$Header: /cvs/stx/stx/libbasic2/BackgroundJob.st,v 1.7 2011-08-03 20:21:20 vrany Exp $'
 !
 
 version_SVN