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

Filecommon/interface/worker.h

Classes IWorker
UWorker

Data types WORKER_TASK

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 iomuxMain 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 * jobTextual 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 taskThe 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 taskThe 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 taskThe 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"){

}