GoWebScanPipeTask.h

Go to the documentation of this file.

/**
* @file    GoWebScanPipeTask.h
* @brief   Declares the GoWebScanPipeTask class
*
* @internal
* Copyright (C) 2017-2026 by LMI Technologies Inc.
* Licensed under the MIT License.
* Redistributed files must retain the above copyright notice.
*/
#ifndef GO_WEB_SCAN_PIPE_TASK_H
#define GO_WEB_SCAN_PIPE_TASK_H

#include <GoWebScanSdk/GoWebScanSdkDef.h>

/**
* @class   GoWebScanPipeTask
* @extends kObject
* @ingroup GoWebScanSdk-Pipe
* @brief   Represents a processing task for the GoWebScanPipe class.
*          Each GoWebScanPipeTask maintains a FIFO queue of messages to process (jobs), and submits jobs to the GoWebScanPipe for execution. 
*          Each GoWebScanPipeTask has at most one pending job submitted to the Pipe for execution at any given time. Multiple jobs associated 
*          with a single task cannot be run in parallel (tasks are assumed to have non-thread-safe state). Each GoWebScanPipeTask
*          is associated with a particular stage (processing priority); multiple tasks can belong to the same stage. Messages are processed 
*          through an execution handler provided to the GoWebScanPipeTask.
*/
typedef kObject GoWebScanPipeTask; 

// Forward declarations
typedef kObject GoWebScanPipe;
typedef kObject GoWebScanPipeMsg;

/** Defines the signature for the job execution handler. */
typedef kStatus(kCall *GoWebScanPipeTaskExecuteFx)(GoWebScanPipeTask task, GoWebScanPipeMsg msg);

/**
* Sets the callback function that is used to execute processing jobs
*
* @public                     @memberof GoWebScanPipeTask
* @param  task                GoWebScanPipeTask object.
* @param  function            Processing execution callback function
* @param  receiver            Receiver argument for callback.
* @return                     Operation status.
*/
GoWebScanFx(kStatus) GoWebScanPipeTask_SetExecuteHandler(GoWebScanPipeTask task, GoWebScanPipeTaskExecuteFx function, kPointer receiver);

/**
* Gets the stage (processing priority) of a task
*
* @public                     @memberof GoWebScanPipeTask
* @param  task                GoWebScanPipeTask object.
* @return                     Stage.
*/
GoWebScanFx(k32u) GoWebScanPipeTask_Stage(GoWebScanPipeTask task);

/**
* Sets the stage (processing priority) of a task
*
* @public                     @memberof GoWebScanPipeTask
* @param  task                GoWebScanPipeTask object.
* @param  stage               Stage.
* @return                     Operation status.
*/
GoWebScanFx(kStatus) GoWebScanPipeTask_SetStage(GoWebScanPipeTask task, k32u stage);

/**
* Adds a message to the processing queue. Dequeues a message at the end of the queue to submit to the pipe 
* for scheduling if no other job is currently pending.
*
* @public                     @memberof GoWebScanPipeTask
* @param  task                GoWebScanPipeTask object.
* @param  message             Message to enqueue.
* @return                     Operation status.
*/
GoWebScanFx(kStatus) GoWebScanPipeTask_Send(GoWebScanPipeTask task, GoWebScanPipeMsg message);

/**
* Gets the maximum capacity of the message queue
*
* @public                     @memberof GoWebScanPipeTask
* @param  task                GoWebScanPipeTask object.
* @return                     Maximum queue capacity.
*/
GoWebScanFx(kSize) GoWebScanPipeTask_MsgCapacity(GoWebScanPipeTask task);

/**
* Sets the maximum capacity of the message queue
*
* @public                     @memberof GoWebScanPipeTask
* @param  task                GoWebScanPipeTask object.
* @param  capacity            Maximum queue capacity.
* @return                     Operation status.
*/
GoWebScanFx(kStatus) GoWebScanPipeTask_SetMsgCapacity(GoWebScanPipeTask task, kSize capacity);

#include <GoWebScanSdk/GoWebScanPipeTask.x.h>

#endif