a class with hook functions where work can be done in a separate thread and wherefrom results are published to the main thread. More...
#include <cuactivity.h>
Public Types | |
| enum | Flags { CuADeleteOnExit = 0x02 , CuAUserFlags = 0x0100 , MaxUserFlags = 0x10000 } |
| enum | ActivityType { PeriodicAType , UserAType = 100 } |
Public Member Functions | |
| CuActivity (const CuData &token) | |
| virtual | ~CuActivity () |
| void | setThread (CuThreadInterface *thread) |
| virtual int | getType () const =0 |
| virtual void | event (CuActivityEvent *e)=0 |
| Receive events from the main thread in the CuActivity thread of execution. More... | |
| virtual int | getFlags () const |
| returns the activity flags More... | |
| void | setFlags (int f) |
| set the flags on the activity More... | |
| void | setFlag (Flags f, bool on) |
| set a specific CuActivity::Flags flag true or false More... | |
| virtual bool | matches (const CuData &token) const =0 |
| virtual int | repeat () const =0 |
| must return the interval of time, in milliseconds, before the next CuActivity::execute call, or zero or negative in order to not execute again More... | |
| void | publishResult (const CuData &data) |
| Publish a result from the activity thread (whence the method is called) to the main thread. More... | |
| void | publishProgress (int step, int total, const CuData &data) |
| Publish a progress from the activity thread (whence the method is called) to the main thread. More... | |
| void | publishResult (const std::vector< CuData > &datalist) |
| Publish a result from the activity to the main thread. Datalist version. More... | |
| void | publishResult (const CuUserData *data) |
| const CuData | getToken () const |
| return the activity token More... | |
| void | setThreadToken (const std::string &tt) |
| const std::string | threadToken () const |
| void | doInit () |
| void | doExecute () |
| void | doOnExit () |
Protected Member Functions | |
| virtual void | init ()=0 |
| virtual void | execute ()=0 |
| virtual void | onExit ()=0 |
| virtual CuThreadInterface * | thread () const |
Detailed Description
a class with hook functions where work can be done in a separate thread and wherefrom results are published to the main thread.
hook functions
Three pure virtual methods are defined by CuActivity abstract class. The code that subclasses implement within those methods are executed in a background thread. When the task is over, the results can be safely delivered to the main thread through the publishResult function. The progress of the ongoing work can also be notified to the main thread with publishProgress.
- init
- execute
- onExit
The init hook
Here subclasses will place initialisation code, for example a tcp connection can be set up The state of the connection or connection errors can be notified on the main thread calling publishResult.
The execute hook
Subclasses will put the main part of the work here. If in the CuActivity::init hook a tcp connection has been successfully established, in the execute hook data can be downloaded from the remote host. The progress of the download can be notified through the publishProgress method. The cuurent step, the total steps and data can be delivered from the background thread to the main thread, where a progress bar on a graphical user interface shows the percentage of the download progress. Activities intended to be executed once are called isolated activities (see below).
The execute method can also be called periodically. For instance, a temperature can be read at regular intervals from a device through the network (see continuous activities, such as CuPeriodicActivity). In this case, subclasses will return a timeout in milliseconds from the CuActivity::repeat function.
The onExit hook
After init and execute finish, the onExit hook is invoked. The code inside onExit, as well as in the two other mentioned hooks, is run in a separate thread. There you would clean up the resources allocated in init and exploited in the execute method. In our example, the tcp connection may be closed. See the Periodic activities section for further details about onExit invocation in continuous activities.
- Note
- Calling publishResult from within onExit requires special attention. You must be sure that listeners have not been destroyed by that time.
Thread of execution
When Cumbia::registerActivity is called to run a new activity, a so called thread token is passed as input argument to the method. The thread token is compared to all other threads running in the same cumbia application using CuThread::isEquivalent. If an equivalent thread is found, it is reused for the new activity. A new thread is started otherwise.
Post data from the background thread to the main
The means to deliver results from the background thread where init is executed and the main thread is the CuData class, that is a key/value bundle. These are the three methods executed in background. They must be implemented in subclasses.
Isolated activities
Isolated activities are designed to be executed once. This means execute is called only once after init. CuActivity::Flags can be set in order to customise the behavior of the activity. In particular, an activity
- can be automatically unregistered after CuActivity::onExit (CuActivity::CuAUnregisterAfterExec flag)
- can be automatically deleted when no longer necessary (CuActivity::CuADeleteOnExit)
CuIsolatedActivity by default enables CuActivity::CuADeleteOnExit and CuActivity::CuAUnregisterAfterExec
If the flag CuAUnregisterAfterExec is set to false, then the activity remains alive after the end of execute and it is possible to exploit this to let the activity wait for further events that wake it up and trigger another execution. For example, the CuEventActivity in the cumbia-tango module and the CuMonitorActivity in the cumbia-epics module set this flag to false in order to wait for events from the Tango or Epics control system engines, respectively.
Periodic activities
In a continuous activity the execute method is called periodically by a timer. To exit the timer, the activity is normally unregistered through Cumbia::unregisterActivity. An exit event interrupts the timer and onExit is invoked at last.
CuActivity::Flags can be set in order to customise the behavior of the activity. CuPeriodicActivity by default enables CuActivity::CuADeleteOnExit and CuActivity::CuAUnregisterAfterExec See the section Isolated activities above for further information about the activity flags.
The period of a continuous activity can either be set before execution or at run time by CuPeriodicActivity::setInterval. The CuPeriodicActivity::getTimeout returns the value of the period. Special events can be sent from the main thread to the background thread in order to temporarily change the state of a CuPeriodicActivity. A continuous activity
- can be paused
- resumed
- explicitly *execute*d
- allows to change its period. See CuPeriodicActivity::event documentation for further details.
Examples
Implementations in the cumbia-tango module
CuPollingActivity
The cumbia-tango module implements CuPeriodicActivity in its CuPollingActivity class, that periodically reads Tango attributes or commands.
CuEventActivity
The cumbia-tango module implements CuActivity in CuEventActivity. CuEventActivity's repeat method returns 0, so that execute is called only once. CuEventActivity could have been derived from CuIsolatedActivity as well.
CuGetTDbPropActivity
CuGetTDbPropActivity from the cumbia-tango module inherits from CuIsolatedActivity so that its execute method is run only once. In fact, CuGetTDbPropActivity connects to the dtabase and reads from it only one time in the execute method.
Observations
As you can see, CuActivity and its isolated and continuous flavours offer enough flexibility to the clients: CuEventActivity directly derives from CuActivity and determines its one shot nature through the repeat method. It could have subclassed CuIsolatedActivity as well. CuPollingActivity benefits from the periodic nature of CuPeriodicActivity. Finally, CuGetTDbPropActivity is an example where only the execute method is really doing work. CuGetTDbPropActivity's init and onExit have empty bodies. See the cumbia-tango module for further reading.
Suspend the background execution of an activity: wait for events and execute callbacks
If the flag CuActivity::CuAUnregisterAfterExec is set to false, the execution of the activity is suspended after execute finishes, as in an event loop. The activity waits for the next event to wake it up and do some job. CuEventActivity from the cumbia-tango module and CuMonitorActivity from the cumbia-epics module benefit from this feature to listen for upcoming events. When an event arrives, the respective callbacks are invoked, the data is extracted from the event and the result is published on the main thread. If CuActivity::CuAUnregisterAfterExec is set to false, Cumbia::unregisterActivity may be needed to exit this activity "*loop*".
Write a simple activity
- md_src_tutorial_cuactivity
Member Enumeration Documentation
◆ ActivityType
◆ Flags
| enum CuActivity::Flags |
Constructor & Destructor Documentation
◆ CuActivity()
| CuActivity::CuActivity | ( | const CuData & | token | ) |
◆ ~CuActivity()
|
virtual |
Member Function Documentation
◆ doExecute()
| void CuActivity::doExecute | ( | ) |
References execute().
Referenced by CuThread::run().
◆ doInit()
| void CuActivity::doInit | ( | ) |
References init().
◆ doOnExit()
| void CuActivity::doOnExit | ( | ) |
References onExit().
◆ event()
|
pure virtual |
Receive events from the main thread in the CuActivity thread of execution.
- Parameters
-
e the event. Activity reimplementations can extend CuActivityEvent to provide custom events Do not delete e after use. Cumbia will delete it after this method invocation.
Implemented in CuPeriodicActivity.
Referenced by CuThread::run().
◆ execute()
|
protectedpure virtual |
Referenced by doExecute(), and CuPeriodicActivity::event().
◆ getFlags()
|
virtual |
returns the activity flags
- Returns
- the activity flags, a combination of values from CuActivity::Flags
- See also
- setFlags
◆ getToken()
| const CuData CuActivity::getToken | ( | ) | const |
return the activity token
The activity token can be used to identify or characterize an activity through a CuData bundle. This must not be confused with the thread token, which is used to decide whether a new activity is started in a new thread or an existing thread with the same token is used.
For that usage, see
- CuThread::matches
- md_src_tutorial_cuactivity
- CuActivity introductive documentation
Activity token is const and set once in the class constructor, though this method is lock free and safe to access from different threads
◆ getType()
|
pure virtual |
Implemented in CuPeriodicActivity.
◆ init()
|
protectedpure virtual |
Referenced by doInit().
◆ matches()
|
pure virtual |
◆ onExit()
|
protectedpure virtual |
Referenced by doOnExit().
◆ publishProgress()
| void CuActivity::publishProgress | ( | int | step, |
| int | total, | ||
| const CuData & | data | ||
| ) |
Publish a progress from the activity thread (whence the method is called) to the main thread.
- See also
- publishResult
◆ publishResult() [1/3]
| void CuActivity::publishResult | ( | const CuData & | data | ) |
Publish a result from the activity thread (whence the method is called) to the main thread.
- Note
- this method may be called even from a thread different from activity's execute. In fact, data is delivered through the event bridge / event loop. An example is cumbia-tango CuEventActivity, where publishResult is invoked from the Tango push_event callback's thread, different from the activity's.
Referenced by CuPeriodicActivity::event().
◆ publishResult() [2/3]
| void CuActivity::publishResult | ( | const CuUserData * | data | ) |
◆ publishResult() [3/3]
| void CuActivity::publishResult | ( | const std::vector< CuData > & | datalist | ) |
Publish a result from the activity to the main thread. Datalist version.
- Parameters
-
datalist a const reference vector of CuData
- Note
- see note in publishResult above
◆ repeat()
|
pure virtual |
must return the interval of time, in milliseconds, before the next CuActivity::execute call, or zero or negative in order to not execute again
- Returns
- an integer greater than zero representing the interval, in milliseconds, before next execution or zero (or negative) to prevent CuActivity::execute to be called again
Implemented in CuPeriodicActivity.
Referenced by CuThread::run().
◆ setFlag()
| void CuActivity::setFlag | ( | CuActivity::Flags | f, |
| bool | on | ||
| ) |
set a specific CuActivity::Flags flag true or false
- Parameters
-
f a flag from CuActivity::Flags on true or false to enable/disable a flag
◆ setFlags()
| void CuActivity::setFlags | ( | int | f | ) |
set the flags on the activity
- Parameters
-
f a combination of CuActivity::Flags ored together.
Referenced by CuPeriodicActivity::CuPeriodicActivity().
◆ setThread()
| void CuActivity::setThread | ( | CuThreadInterface * | thread | ) |
References thread().
Referenced by Cumbia::registerActivity().
◆ setThreadToken()
| void CuActivity::setThreadToken | ( | const std::string & | tt | ) |
Referenced by CuThread::registerActivity().
◆ thread()
|
protectedvirtual |
Referenced by setThread().
◆ threadToken()
| const std::string CuActivity::threadToken | ( | ) | const |
The documentation for this class was generated from the following files:
