Worker
IWorker interface provides the framework for user implemented tasks to be run in a thread. The interface consists of a function to schedule tasks and three callbacks for: success, failure and progress
File information
Classes
IWorker
class IWorker {
public:
static IWorker* Create(class IIoMux * const iomux,unsigned int numThreads);
virtual ~IWorker();
virtual void WorkerScheduleJob(const char * job, WORKER_TASK workerTask, class UWorker * const user);
};
Public functions
Create (static function)
-
Creates an instance of IWorker. iomux is the main thread's iomux control. It is used to run the callbacks in the main thread context.numThreads sets the maximum number of concurrently running threads. Note: each user defined task that runs under the IWorker control operates in a single thread. The numThreads parameter (if it is > 1) comes into play when another task is scheduled before the previously scheduled is still running. Then a second, third,.., thread is started until the numThreads limit is reached. In this case the actual request is queued and processed as soon as one of the threads terminates.
Parameters
| class IIoMux * const iomux | Main threads IoMux instance pointer |
| unsigned int numThreads | The number of parallel threads to allocate for jobs |
Return value
Returns the allocated class IWorker*.
~IWorker (destructor fuction)
-
The class IWorker destructor.
WorkerScheduleJob (virtual void function)
-
Starts the textual task description in the user defined WORKER_TASK workerTask. The results and progress indications are returned to the main thread via the functions defined in the UWorker class.
log is used to log AppInstance related logs depedent of the log flag LOG_WORKER. When the IWorker framework processes a job request, it calls the workerTask function with the parameter "job" given in the WorkerScheduleJobcall.
Parameters
| const char * job | Textual description of job |
| WORKER_TASK workerTask | User defined function that is called by the IWorker interface and implements the job that is to be carried out in a thread |
| user | The class that uses the Iworker interface |
UWorker
class UWorker {
public:
void WorkerJobComplete(class IWorker * const task, const char * jobResult);
void WorkerJobFailed(class IWorker * const task, int error);
void WorkerJobProgress(class IWorker * const task, const char * notification);
};
Public functions
WorkerJobComplete (callback fuction)
-
This function is called after successful completion of the scheduled job. Parameters: "class IWorker * const task": the IWorker instance the job was processed by. "const char * jobResult": the result string returned in int(*WORKER_TASK)(.., char** result,..);.
Parameters
| class IWorker * const task | The class IWorker instance that issues this callback |
| const char * jobResult | Text string generated by the worker task |
WorkerJobFailed (callback fuction)
-
This function is called after unsuccessful completion of the scheduled job. Parameters: "class IWorker * const task": the IWorker instance the job was processed by. "int error": the error (!=0) return code returned by WORKER_TASK;.
Parameters
| class IWorker * const task | The class IWorker instance that issues this callback |
| int error | Error code generated by the worker task |
WorkerJobProgress (callback fuction)
-
This function is called if the WORKER_TASK calls the NOTIFICATION_FUNC during operation. Parameters: "class IWorker * const task": the IWorker instance the job was processed by. "const char * notification": the notification text;
Parameters
| class IWorker * const task | The class IWorker instance that issues this callback |
| const char * notification | Textual notification generated by the worker function to be passed back to the main thread |
Data types
WORKER_TASK
typedef int(*WORKER_TASK)(const char * job, class UWorker * const user, char** result, class IWorker * const task, NOTIFICATION_FUNC notificationFunc);
Overview
WORKER_TASK This is the prototype of the function the user creates and passes to the IWorker framework to execute. Parameter description: "const char * job": the textual parameter string as given in WorkerScheduleJob(const char * job,...). "class UWorker * const user": the job requesting classe's own "this". DO NOT USE IT IN YOUR WORKER FUNCTION! It is there to be passed subsequently to the notification function to pass back progress calls to your user class "char** result": output parameter for the worker function. There a char* container with the result of a SUCCESSFUL operation is stored. NOTE: The container is freed by the worker framework when all processing is completed. DO NOT FREE IT YOURSELF! "class IWorker * const task": passthrough parameter for IWorker operation. DO NOT USE IT IN YOUR WORKER FUNCTION OTHER THAN PASSING IT TO "NOTIFICATION_FUNC notificationFunc"! "NOTIFICATION_FUNC notificationFunc": this is a function provided by the IWorker framework that your worker function can call to asyncronously pass back information to your user class during operation. e.g. progress information return code: "0" indicates success and leads to a WorkerJobComplete(..) callback, otherwise the WorkerJobFailed(.., int error) is called and the return code is passed in "error".
Return value
Returning 0 indicates success and leads to a WorkerJobComplete(..) callback, otherwise the WorkerJobFailed(.., int error) is called and the return code is passed in "error" .
NOTIFICATION_FUNC
typedef void(*NOTIFICATION_FUNC)(class UWorker * const user, class IWorker * const task, char* notification);
Overview
NOTIFICATION_FUNC Parameter description: "class UWorker * const user": passthrough to the IWorker, given as parameter to your worker function. "char** result": output parameter for the worker function. There a char* container with the result of a SUCCESSFUL operation is stored. NOTE: The container is freed by the worker framework when all processing is completed. "class IWorker * const task": passthrough parameter for IWorker operation. "char* notification": textual information to be passed back to your requesting user class. .
Code Example
/*
This example shows the code to schedule 3 jobs to convert pcap files containing voice data to wave audio
*/
// app class definition
class myApp : public UWorker {
...
virtual void WorkerJobComplete(class IWorker * const task, const char * jobResult);
virtual void WorkerJobProgress(class IWorker * const task, const char * notification);
virtual void WorkerJobFailed(class IWorker * const task, int error);
...
}
#define MAX_NUM_THREADS 2
myApp::myApp(IIoMux * iomux)
: iomux(iomux)
{
// in this example the thread worker system is created in the main constructor, but it can be created whenever deemed necessary
IWorker* worker = IWorker::Create(iomux,MAX_NUM_THREADS);
// since MAX_NUM_THREADS is 2 the next 2 jobs are started immediately
// the first parameter ("Convert2Wave: PhoneCall-645.pcap") is used for display purposes
worker->WorkerScheduleJob("Convert2Wave: PhoneCall-645.pcap", WorkerFunc, this);
worker->WorkerScheduleJob("Convert2Wave: PhoneCall-389.pcap", WorkerFunc, this);
// if the 2 previously started threads are still running this job is queued and processed as soon as one of the former completes
worker->WorkerScheduleJob("Convert2Wave: PhoneCall-123.pcap", WorkerFunc, this);
}
// when the first thread starts your worker function will be called:
#define SOME_ERROR -1
int WorkerFunc("Convert2Wave: PhoneCall-645.pcap", class UWorker* user, char** result, class IWorker * const task, NOTIFICATION_FUNC notificationFunc){
... read job description: Convert2Wave: PhoneCall-645.pcap ...
... open PhoneCall-645.pcap ...
// if you wish to send a notification do so: (the "notificationFunc" inside the worker interface will subsequently call the WorkerJobProgress callback
notificationFunc(user, task, "Estimated time: 13 sec");
... convert ...
// something goes wrong:
return SOME_ERROR;
// all went well
char* resultString=(char*)malloc();
sprintf(resultString,"Converted File: PhoneCall-645.wav");
*result=resultString;
return 0;
}
// when your Worker function completes successfully:
void app::WorkerJobComplete(class IWorker * const task, "Converted File: PhoneCall-645.wav"){
}
// when your Worker function failes:
void app::WorkerJobFailed(class IWorker * const task, SOME_ERROR){
}
// progress callback: (will be called by the notificationFunc)
void app::WorkerJobProgress(class IWorker * const task, "Estimated time: 13 sec"){
}