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"
{

///   @brief 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 );

///   @brief 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_