--- 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