# 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

File | common/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 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"){

    }