Progress bars and background tasks and thread control
DCL to CML changes under way
We've copied the DCL docs to this new location and are still in the process of scrubbing the pages and fixing all the text and links. If you notice anything amiss feel free to please post a comment at the bottom of the page. Thanks!
I recently wrote about a thread-safe class for displaying information from background processes. The class worked fine, but it exercised absolutely no control over the thread itself. That is, in the accompanying app it was possible to launch multiple instances of the same worker thread, with amusing if not disastrous results, and it was also possible to close the test program before all background tasks had completed, with disastrous and not at all amusing results.
What I needed was a class to remedy these deficiencies.
I’ve covered this ground before – in Classes for Background Processes in Clarion Magazine I introduced a class for managing background threads. It’s a tricky business mixing classes and threading because you can’t Start() a method (which would be handy); you can only Start() a procedure.
There are two kinds of code to consider when running background processes: 1) the code that executes once for each time through the processing loop, and 2) the thread control code, for tasks such as knowing when the thread is running and pausing or closing the thread on demand.
Short of using global variables (not generally a good idea) my standard approach is to put the thread management code in a class, and then pass a class instance to the Start()ed procedure. I explained how to do that in the previous article.
But once you have the class instance in the Start()ed procedure, there are at least two different ways to handle the code. One, which is the approach I used in the ClarionMag article, is to create a DoTask method that sits inside a loop. To use DoTask you need to derive the method and load it up with whatever code should execute each time through the loop.
In my recent background task progress bars example I went for a marginally simpler approach: the Start()ed task procedure looks like any other process but includes a bit of code before, after, and inside the loop to handle the control aspect. I still need to derive a virtual method, but in this case it’s the method that does the actual Start()ing.
Adding thread control
My first challenge was to modify my original threading class to handle starting and stopping a single instance of a Start()ed procedure.
Here’s what the demo procedure looks like:
MEMBER('ThreadDemo')
MAP
END
ThreadDemo_Main procedure
Window WINDOW('Background thread demo'),AT(,,223,101),GRAY,FONT('Microsoft Sans ' & |
'Serif',8),TIMER(1)
BUTTON('Stop Task'),AT(114,26,70),USE(?StopTask)
BUTTON('Start Task'),AT(28,26,70,14),USE(?StartTask)
STRING('Background process is not running'),AT(28,51),USE(?status)
END
Task class(DCL_System_Threading_Thread)
StartWorkerProcedure procedure,derived
end
CODE
open(window)
accept
case event()
of EVENT:CloseWindow
if not Task.Stopped()
message('Cannot exit while the background Task is running!')
cycle
end
of EVENT:Timer
?status{prop:text} = choose(Task.Stopped(),'Background process is not running','Background process is running')
end
case accepted()
of ?StopTask
Task.Stop()
of ?StartTask
Task.Start()
end
end
close(window)
Task.StartWorkerProcedure procedure!,derived
code
start(ThreadDemo_BackgroundProcess,25000,address(self))
Note that I’ve derived the StartWorkerProcedure method which calls my actual background process. This can be any procedure that executes code in a loop, such as a report or a process.
Here’s the ThreadDemo_BackgroundProcess procedure:
MEMBER('ThreadDemo')
MAP
END
ThreadDemo_BackgroundProcess procedure(string address)
Thread &DCL_System_Threading_Thread
sleeptime long
loopcount long
CODE
Thread &= (address)
if Thread &= NULL
return
end
Thread.WorkerProcedureHasStarted()
! Implement your own loop structure as you see fit, but be sure to include the code
! to terminate the thread as shown in this loop. Your loop will probably not have a fixed
! number of iterations - this one does simply so it doesn't go on forever.
loop 10 times
if Thread.StopRequested() then break.
! Do something here. This is a demo procedure so all it does is sleep.
sleep(500)
end
Thread.WorkerProcedureHasEnded()
The procedure's code is almost all thread control code because it is, after all, just a demo.
The DCL_System_Thread is class is really pretty simple. For the most part it revolves around two flags, Running and StopRequested. Here’s the class header:
DCL_System_Threading_Thread Class,Type,Module('DCL_System_Threading_Thread.CLW'),Link('DCL_System_Threading_Thread.CLW',_DCL_Classes_LinkMode_),Dll(_DCL_Classes_DllMode_)
Running byte,private
StopRequest byte,private
Construct Procedure()
Destruct Procedure()
Start procedure
StartWorkerProcedure procedure,virtual
Stop procedure
Stopped procedure,bool
StopRequested procedure,bool
WorkerProcedureHasEnded procedure
WorkerProcedureHasStarted procedure
End
And here’s the class code:
DCL_System_Threading_Thread.Construct Procedure()
code
self.StopRequest = false
self.Running = false
DCL_System_Threading_Thread.Destruct Procedure()
code
DCL_System_Threading_Thread.Start procedure
code
if ~self.running
self.StartWorkerProcedure()
end
DCL_System_Threading_Thread.StartWorkerProcedure procedure!,virtual
code
! To use this class you will typically create a derived class somewhere in your
! application code, probably in the procedure that launches your worker
! procedure.
DCL_System_Threading_Thread.Stop procedure
code
self.StopRequest = true
DCL_System_Threading_Thread.Stopped procedure!,bool
code
return choose(self.running=false,true,false)
DCL_System_Threading_Thread.StopRequested procedure!,bool
code
return self.StopRequest
DCL_System_Threading_Thread.WorkerProcedureHasEnded procedure
code
self.Running = FALSE
self.StopRequest = false
DCL_System_Threading_Thread.WorkerProcedureHasStarted procedure
code
self.running = true
self.StopRequest = false
Note that the Start() method calls the StartWorkerProcedure method, but only if the thread isn’t already running. And StartWorkerProcedure is the one you derive so you can call your own process. You never call StartWorkerProcedure directly – it’s always called automatically by the base class’s Start() method.
Here’s the demo app in action:
You can click on Start Task as many times as you like, but the Start() only executes if there is no existing running process. Clicking Stop Task will cause the process to terminate on the next loop.
If you try to exit the program while the task is running, you’ll see this message:
Everything works just fine. But there’s no indication of the task’s background process yet.
It’s conceivable that a background task will need to run without updating a UI somewhere, so I don’t necessarily want to add UI capabilities to this class. Instead I created a derived class called DCL_System_Threading_DisplayedThread. Here’s the header:
DCL_System_Threading_DisplayedThread Class(DCL_System_Threading_Thread),Type,Module('DCL_System_Threading_DisplayedThread.CLW')|
,Link('DCL_System_Threading_DisplayedThread.CLW',_DCL_Classes_LinkMode_),Dll(_DCL_Classes_DllMode_)
UI &DCL_UI_BackgroundProgressDisplay
Construct Procedure()
Destruct Procedure()
End
And here’s the code:
DCL_System_Threading_DisplayedThread.Construct Procedure()
code
self.UI &= new DCL_UI_BackgroundProgressDisplay
DCL_System_Threading_DisplayedThread.Destruct Procedure()
code
dispose(self.UI)
As you can see, all this class does is create an instance of DCL_UI_BackgroundProgressDisplay, which I introduced last time.
I modified my two-task demo from the previous article, with the code as follows:
MEMBER('ThreadDemo')
MAP
END
ThreadDemo_Main procedure
Window WINDOW('Background task progress bars'),AT(,,434,104),GRAY,FONT('Microsof' & |
't Sans Serif',8)
BUTTON('Start task 1'),AT(15,19,51,19),USE(?StartTask1),ICON(ICON:None)
STRING('Message'),AT(148,18,253),USE(?Message1)
PROGRESS,AT(148,31,253,6),USE(?PROGRESS1),RANGE(0,100)
BUTTON('Start task 2'),AT(15,57,51,19),USE(?StartTask2),ICON(ICON:None)
STRING('Message'),AT(148,56,253,10),USE(?Message2)
PROGRESS,AT(148,70,253,6),USE(?PROGRESS2),RANGE(0,100)
BUTTON('Stop task 1'),AT(78,19,51,19),USE(?StopTask1),ICON(ICON:None)
BUTTON('Stop task 2'),AT(78,57,51,19),USE(?StopTask2),ICON(ICON:None)
END
Task1 class(DCL_System_Threading_DisplayedThread)
StartWorkerProcedure procedure,derived
end
Task2 class(DCL_System_Threading_DisplayedThread)
StartWorkerProcedure procedure,derived
end
CODE
open(window)
accept
case event()
of EVENT:OpenWindow
task1.UI.Enable()
task2.UI.Enable()
of EVENT:CloseWindow
if not Task1.Stopped() or not Task2.Stopped()
message('Please wait until the background processes complete')
cycle
end
end
case accepted()
of ?StartTask1
Task1.Start()
of ?StartTask2
Task2.Start()
of ?StopTask1
Task1.Stop()
of ?StopTask2
Task2.Stop()
end
end
close(window)
Task1.StartWorkerProcedure procedure!,derived
code
self.ui.SetProgressControlFEQ(?progress1)
self.ui.SetStringControlFEQ(?Message1)
start(ThreadDemo_BackgroundProcess,25000,address(self),100,100)
Task2.StartWorkerProcedure procedure!,derived
code
self.ui.SetProgressControlFEQ(?progress2)
self.ui.SetStringControlFEQ(?Message2)
start(ThreadDemo_BackgroundProcess,25000,address(self),100,100)
There are two additions here. First, the calls to Taskx.UI.Enable() in the OpenWindow event, and second the Taskx.UI.SetProgressControlFEQ and Taskx.UI.SetStringControlFEQ calls in the derived StartWorkerProcedure methods.
The background procedure now looks like this, with the addition of two method calls to set the progress bar and the progress message values.
ThreadDemo_BackgroundProcess procedure(string address, string delay, string count)
Task &DCL_System_Threading_DisplayedThread
sleeptime long
loopcount long
x long
CODE
Task &= (address)
if Task &= NULL
return
end
Task.WorkerProcedureHasStarted()
sleeptime = delay
loopcount = count
! Implement your own loop structure as you see fit, but be sure to include the code
! to terminate the thread as shown in this loop. Your loop will probably not have a fixed
! number of iterations - this one does simply so it doesn't go on forever.
loop x = 1 to loopcount
if Task.StopRequested() then break.
! Do something here. This is a demo procedure so all it does is sleep.
task.UI.SetProgressControlValue(x)
task.UI.SetStringControlValue(x / loopcount * 100 & ' percent done')
sleep(sleeptime)
end
Task.WorkerProcedureHasEnded()
Here’s the demo program in action. It functions just as the other demo did but it now updates the window with the progress status. Again, you can only run one instance of either task at once and you cannot exit the program until all tasks have completed.
As with the non-UI example, if you attempt to exit the program before the tasks finish you'll get an error message. In fact the background tasks continue to run while the error message is displayed, although the UI doesn't update because the Message() statement is blocking the Accept loop. As soon as you close the Message window the window is updated with the current task status.
The only thing missing now is a template to make this really easy to use…