 |
Workspace 7.0.2
|
|
Workspace 7.0.2
|
Updates a workspace. More...
#include <Workspace/DataExecution/Execution/updater.h>
Public Types | |
| enum | ExecutionMode { ExecuteContinuously , ExecuteOnce } |
 Public Types inherited from Task | |
| enum | State { Dormant , Scheduled , Running , Aborted , Finished } |
| enum | TaskBehaviour { GrowThreadPool = 0x01 , AutoDelete = 0x02 , RunRemotely = 0x04 } |
Additional Inherited Members | |
| Signals inherited from Task | |
| void | aborted () |
| void | finished () |
| void | started () |
| Protected Member Functions inherited from Observable | |
| Observable () | |
| Observable (const Observable &) | |
| virtual void | doTask ()=0 |
An instance of Updater is created for each thread of execution used by workspaces in an application. Workspaces each have an Updater associated with them, with child workspaces generally sharing the Updater of their parent. The main exception to this is when the child workspace(s) have been explicitly configured to run in their own Updater.
Clients would not normally create their own Updater instance directly. This process is normally done automatically by a workspace whenever the Updater is needed internally. Clients can call Workspace::getUpdater() and the Updater will be created if necessary as part of that call. This is particularly important when nested workspaces are taken into consideration, since the process of re-parenting a workspace can delete an Updater which was previously created for the workspace before it had any parent workspace. If clients only ever call Workspace::getUpdater() and never construct their own Updater instance, the lifetime of the various Updaters will be properly managed behind the scenes automatically.
An Updater will not be running when it is first created. In order to actually allow execution to occur, something has to call the Updater's start() member function. This will start up the thread's event loop and set it processing the items that have been passed to it for keeping up to date. Once it has done these things, it will return immediately without waiting for those things to finish. The caller can check whether a thread is running with isRunning() and it can attach an observer for ExecutionFinishedEvent notifications if it wants to be notified when something causes the thread to stop (generally a workspace execution error or an explicit call to the stop() member function). Clients can also use the wait() member function to block their own thread until the Updater stops, but be aware that this would only make sense if either the Updater is not running in continuous mode or if some other thread will cause the Updater to stop. Clients can also use the getLastResult() member function to check whether the last time the Updater stopped was due to an error or through normal means.
All events considered part of the Updater API will be subclasses of ExecutionEvent. Other events may be issued by an Updater, but they are either forwarded from elsewhere or are meant for internal use.
| enum ExecutionMode |
| Updater | ( | ) |
|
overridedefault |
| void addToUpdateSet | ( | Updatable & | updatable, |
| bool | addToFront = false |
||
| ) |
| updatable | The updatable object to add to the update set. If it is already in the set, its reference count will be increased by one. |
| addToFront | Add the updatable to the front. If it is already in the set, move it to the front. |
When processUpdateSet() is called, all objects in the update set will be brought up to date by the execution thread. It is allowable to add more objects to the update set during execution, since addToUpdateSet() is threadsafe.
The order in which updates occur is undefined. So as to ensure that all objects in the set are updated fairly, the order is rotated during execution. If the order of evaluation is important, this needs to be expressed in the workspace itself via dependency relationships.
Although you can add and remove items to/from the update set during execution, you cannot add and remove the objects themselves to/from the workspace while execution is taking place.
The items in the update set are reference-counted. Each call to addToUpdateSet() must eventually have a matching call to removeFromUpdateSet().
| void clearErrorSource | ( | ) |
This function clears the current error source and raises an ExecutionErrorEvent notification before returning
| Updatable * currentUpdatableCausingQueuing | ( | ) |
| bool currentUpdateIsDelayed | ( | ) | const |
| void delayCurrentUpdate | ( | Updatable & | delayedSource | ) |
| delayedSource | This should be the object on which the current update is being delayed. It is only needed in case the execution thread ends up detecting a circular dependency and needs to provide an object within that circular dependency along with its AbortExecutionEvent notification. |
Calling this funciton informs the execution thread that whatever it is currently trying to bring up to date, it needs to be delayed because it relies on something else. This normally only applies to something inside some kind of loop requesting to be updated before the loop itself. By delaying the object's update until after the loop, it will be updated in due course anyway as part of the loop processing.
|
overridevirtual |
Performs the task of updating a set of updatable objects.
Implements Task.
| void flushLog | ( | ) |
Ensures that all data sent to the log has been flushed. This usually only matters when data is being sent to a file and the text is being buffered, but buffering may also be used on other log destinations as well. Calling flushLog() ensures that all text has been sent to the logging destination.
| Updatable * getErrorSource | ( | ) | const |
| Updater::ExecutionMode getExecutionMode | ( | ) | const |
| bool getStopRequested | ( | ) | const |
| QObject * getThreadObject | ( | ) |
This function is mostly useful when you want to parent something to a QObject that belongs to an execution thread. When the execution thread stops, the QObject is destroyed and so will all of the QObject's children. Client code should not try to use the returned QObject for anything other than setting it as parent for something else.
| bool isPaused | ( | ) | const |
| bool isReadyToProcessUpdateRequests | ( | ) | const |
Returns true if the Updater is ready to start processing events.
| bool isRunning | ( | ) |
Returns true if the Updater is running.
| void logText | ( | const QString & | msg | ) |
| msg | The message to log. |
|
overridevirtual |
Reimplemented from Task.
| void pauseUpdate | ( | ) |
| void popUpdatableToQueueChangesOn | ( | Updatable & | u | ) |
Pop an Updatable off the queue changes list
| void processUpdateSet | ( | ) |
Request that the updater thread brings all items in the update set up to date. This function can be called multiple times and without fear of accumulating unnecessary requests for an update. The thread will ensure that no more than one pending processing request is created. Extra requests are simply discarded.
It is also safe to call this function even if the execution thread is not running, since the function call raises a notification that the thread responds to only if it is running.
| void pushUpdatableToQueueChangesOn | ( | Updatable & | u | ) |
If an Updatable wants all data changes to be queued while it is updating then it can push itself onto this list. The DataUpdater observer will check the top of this list and wont give WidgetConnectors a chance to make any changes during PauseUpdate events if something is there.
| void removeFromUpdateSet | ( | Updatable & | updatable | ) |
| updatable | The updatable object to remove from the update set. It will have its reference count decreased by one and will only be actually removed if the reference count for it drops to zero. |
When processUpdateSet() is called, all objects in the update set will be brought up to date by the execution thread. It is allowable to remove an object from the update set during execution, since this function is threadsafe. Note, however, that it is not allowable to delete an object during execution. Were an object to be removed, it would be possible that the thread is currently updating it, so callers cannot do anything with an object while execution is in progress.
The items in the update set are reference-counted. Each call to removeFromUpdateSet() should have had a matching addToUpdateSet() in the past. Only once the reference count drops to zero will the item actually be removed from the update set, since while the reference count is a positive number, something still wants it to be updated.
| void requestStop | ( | ) |
Request that the updater thread stops, but let it try to do so gracefully. This normally means allowing the currently executing operation to complete before stopping. If you really want the thread to stop straight away, call terminate() instead. Note, however, that this will likely result in corrupted data.
| void resetStopRequestFlag | ( | ) |
| void setErrorSource | ( | Updatable & | errorSource | ) |
| errorSource | The object that has just encountered an error during execution. |
This function is typically called by Operation::update() when a call to its execute() function fails. The call to setErrorSource() is made just before update() returns false. The main purpose of this call is to allow interested parties to be notified of the error and to be able to find out what the source of the error was. Note that any error message should already have been output by the operation and so is not available nor required here.
This function will raise an ExecutionErrorEvent notification before returning.
| void setExecutionMode | ( | ExecutionMode | mode | ) |
Configures the execution mode of the UpdaterImpl.
| mode | The execution mode. |
| void stopAndWaitUntilFinishedRunning | ( | ) |
Requests the updater thread stop and waits (i.e. blocks) until the workspace has finished being updated.
| void terminate | ( | ) |
Cause the thread to stop execution immediately. This is generally not recommended, since it will likely result in corrupted data. This function is a blunt instrument to be used only in desperate situations (typically error handling and aborting an application). Clients should prefer to call stop() instead where possible.