IJob.h

Go to the documentation of this file.

/********************************************************************
*
*   Project     Artec 3D Scanning SDK
*
*   Purpose:    Job interface.
*
*   Copyright:  Artec Group
*
********************************************************************/

#ifndef _IJOB_H_
#define _IJOB_H_

#include <artec/sdk/base/BaseSdkDefines.h>
#include <artec/sdk/base/IRef.h>
#include <artec/sdk/base/Errors.h>

namespace artec { namespace sdk { namespace base
{

class  IJob;
class  IJobObsever;
struct AlgorithmWorkset;

extern "C"
{
/*
*   Synchronously execute a job in several threads
*   @param job - this parameter is an algorithm or a procedure, 
*   and it should be created with appropriate function like createXXXAlgorithm()
*   or createXXXProcedure(). TRef should be used to hold this pointer, 
*   so the lifetime of the object will be cared of accordingly. 
*   @param workset - this parameter is a simple structure which can be 
*   created on stack or in dynamic memory. All his interface members,
*   such in, out, progress (if any) or cancellation (if any) should live till
*   the end of the job processing so please take care of that. 
*/
ErrorCode ABASESDK_LINK_SPEC
    executeJob( IJob* job, const AlgorithmWorkset * workset );

/*
*   Asynchronously launch a job in several threads
*   @param job - this parameter is an algorithm or a procedure, 
*   and it should be created with appropriate function like createXXXAlgorithm()
*   or createXXXProcedure(). TRef should be used to hold this pointer, 
*   so the lifetime of the object will be cared of accordingly. 
*   @param workset - this parameter is a simple structure which can be 
*   created on stack or in dynamic memory. All his interface members,
*   such in, out, progress (if any) or cancellation (if any) should live till
*   the end of the job processing so please take care of that. 
*   @param jobObsever - this parameter is intended to receive notifications 
*   about job completeness. The particular class inheriting JobObseverBase should be defined and 
*   implemented by user, and TRef should  be used to hold this pointer.  
*   The lifetime of this object will be cared of as well. 
*/
ErrorCode ABASESDK_LINK_SPEC
    launchJob( IJob* job, const AlgorithmWorkset * workset, IJobObsever* jobObsever );
}

/*  Job Interface. 
*   Used by executeJob and launchJob  
*   Base for algorithms family and scanning
*/
///@see executeJob, launchJob
class IJob : public IRef
{
public:
    /// Returns short job name for debug purposes
    virtual const char* getDebugName() const = 0;

    ///< Returns the required number of threads
    ///<@retval 0   Any positive number of threads is applicable.
    ///<@retval >0  The returned number of threads is mandatory.    
    virtual unsigned int getThreadsRequired() const = 0;

    ///< Sets up the environment, makes a processing schedule
    ///< @note  It's called only for the first working thread
    virtual ErrorCode start( const AlgorithmWorkset* runSet ) = 0;

    ///< Executes the algorithm's processing
    ///< @note  It's called for all working threads 
    virtual ErrorCode process( int threadIndex ) = 0;

    ///< Sums everything up in the end
    ///< @note  It's called only for the last working thread in case 
    ///<        everything went ok and with no abortions
    virtual ErrorCode finish() = 0;

    ///< Cleans up the environment
    ///< @note  The routine is called for the last working thread even if an error occurs
    virtual ErrorCode reset() = 0;
};

} } } // namespace artec::sdk::base

#endif // _IJOB_H_