public interface IControlledThread extends INormalThread
Key methods to control a IControlledThread
:
requestPause()
to pause it
requestUnpause()
to unpause it
requestCancel()
to cancel it
INormalThread.waitToFinish()
to wait for the thread to end
close()
to cancel the thread and wait for it to end
3 examples of proper usage of IControlledThread
s:
IControlledThread ct; // If your runnable needs the reference: must be instance attribute or else a reference wrapper // The simplest and clearest: ct = factory.newControlledThread( "Example #1", new Runnable() { public void run() { while ( ct.mayContinue() && !done() ) doSomeWork(); } } ); // A lower lever usage/implementation: ct = factory.newControlledThread( "Example #2", new Runnable() { public void run() { while ( !ct.isCancelRequested() && !done() ) { if ( ct.waitIfPaused() ) continue; // If execution was paused, "continue" so cancellation will be checked again first doSomeWork(); } } } ); // Usage/implementation when task is to walk a file tree (Files.walkFileTree()): ct = factory.newControlledThread( "Example #3", new Runnable() { public void run() { try { Files.walkFileTree( folder, new SimpleFileVisitor< Path >() { @Override public FileVisitResult visitFile( Path file, BasicFileAttributes attrs ) throws IOException { if ( !ct.mayContinue() ) return FileVisitResult.TERMINATE; doSomethingWithFile( file ); return FileVisitResult.CONTINUE; } } ); } catch ( IOException ie ) { ie.printStackTrace(); } } } ); // To start the controlled thread in each case: ct.start();
IFactory.newControlledThread(String, Runnable)
,
IJob
Modifier and Type | Method and Description |
---|---|
void |
close()
Properly closes this thread and waits for it to die.
|
IControlledState |
getControlledState()
Returns the controlled state of the thread.
|
long |
getExecTimeMs()
Returns the execution time in ms.
|
long |
getPausedTimeMs()
Returns the time spent waiting in paused state.
|
boolean |
guestMayContinue()
Returns true if the job's thread is allowed to continue.
|
boolean |
guestWaitIfPaused()
If job's execution is paused, this method will block the caller thread until the execution is unpaused or cancelled.
|
boolean |
isCancelRequested()
Tells whether a cancel has been requested.
|
boolean |
isPauseRequested()
Tells whether a pause has been requested.
|
boolean |
mayContinue()
Returns true if the thread is allowed to continue.
|
void |
requestCancel()
Requests canceling of the execution of the thread.
|
void |
requestPause()
Requests pausing of the execution of the thread.
|
void |
requestUnpause()
Requests unpausing of the execution of the thread from a paused state.
|
boolean |
waitIfPaused()
If execution is paused, this method will block the thread until the execution is unpaused or cancelled.
|
asThread, checkedSleep, start, waitToFinish
void requestCancel()
void requestPause()
void requestUnpause()
boolean isCancelRequested()
IControlledThread
users are responsible to periodically check this whether they are allowed to continue their work or they have to return in
order to end the thread.
boolean isPauseRequested()
IControlledThread
users are responsible to periodically check this whether they are allowed to continue their work or they have to wait for
either an unpause or cancel request.
IControlledState getControlledState()
boolean waitIfPaused()
This method should be called when the executing thread wants to wait while the execution is paused, because this method properly sets the controlled
state to IControlledState.PAUSED
while waiting, and also properly handles execution times regarding wait time counting toward the paused time.
Time waited inside this method is properly excluded from execution time and is included in the paused time (getPausedTimeMs()
).
If the executing thread implementation waits in some other way (e.g. using Thread.sleep(long)
, those are included in the execution time.
WARNING! This method can only be called from the job's executing thread!
mayContinue()
,
guestMayContinue()
boolean mayContinue()
Besides checking and returning the inversion of isCancelRequested()
this method also waits if pause is requested (but returns false if cancel is
requested while in the paused state).
WARNING! This method can only be called from the job's executing thread!
waitIfPaused()
,
guestMayContinue()
boolean guestWaitIfPaused()
This method should only be called from guest threads, meaning threads other than the job's executing thread.
Purpose of this method is for example if the job spawns more threads and they want to respect the owner job's paused state.
WARNING! This method is not for the job's executing thread!
guestMayContinue()
boolean guestMayContinue()
Besides checking whether job was requested to be cancelled this method also waits if job pause is requested (but returns false if cancel is requested while in the paused state).
Purpose of this method is for example if the job spawns more threads and they want to respect the owner job's paused state.
WARNING! This method is not for the job's executing thread!
guestWaitIfPaused()
long getPausedTimeMs()
long getExecTimeMs()
void close()
First calls requestCancel()
and then waits for this thread to die by calling INormalThread.waitToFinish()
.
This API documentation is public and is intended for / allowed to be used by anyone.
Scelight home page: https://sites.google.com/site/scelight/
Scelight is a trademark of András Belicza. Copyright © András Belicza, 2013-2015. All rights reserved.