GoWebScanPipe.h

Go to the documentation of this file.

/**
* @file    GoWebScanPipe.h
* @brief   Declares a GoWebScanPipe object.
*
* @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_H
#define GO_WEB_SCAN_PIPE_H

#include <GoWebScanSdk/GoWebScanSdkDef.h>
#include <GoWebScanSdk/GoWebScanPipeMsgPool.h>
#include <GoWebScanSdk/GoWebScanPipeMsg.h>

/**
* @class   GoWebScanPipe
* @extends kObject
* @ingroup GoWebScanSdk-Pipe
* @brief   Represents a pipeline to run sequences of processing tasks concurrently. A GoWebScanPipe object 
*          coordinates executing GoWebScanPipeTask objects that have received a GoWebScanPipeMsg, and coordinates 
*          passing messages from task to task as processing steps execute. The pipe maintains a a priority 
*          queue of processing jobs, ordered by stage, and a thread pool to execute jobs.  Higher priority 
*          jobs (higher stage number) are dispatched for processing before lower priority jobs. 
*/
typedef kObject GoWebScanPipe; 

// Forward declaration
typedef kObject GoWebScanPipeTask;

/** Defines the signature of the handler used by tasks to receive a message from the pipe. */
typedef kStatus(kCall *GoWebScanPipeSendFx)(kPointer context, GoWebScanPipeMsg msg);

/**
* Constructs a GoWebScanPipe object.
*
* @public                   @memberof GoWebScanPipe
* @param  pipe              Receives the constructed GoWebScanPipe object. 
* @param  allocator         Memory allocator (or kNULL for default). 
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanPipe_Construct(GoWebScanPipe* pipe, kAlloc allocator);

/**
* Sets the number of threads to be used by the pipe. If not set, the thread count will
* default to the maximum number of processors available in the host.
*
* @public                   @memberof GoWebScanPipe
* @param  pipe              GoWebScanPipe object. 
* @param  count             Thread count. 
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanPipe_SetThreadCount(GoWebScanPipe pipe, kSize count);

/**
* Gets the number of threads to be used by the pipe
*
* @public                   @memberof GoWebScanPipe
* @param  pipe              GoWebScanPipe object. 
* @return                   Thread count. 
*/
GoWebScanFx(kSize) GoWebScanPipe_ThreadCount(GoWebScanPipe pipe);

/**
* Adds a task to the pipe.
*
* @public                   @memberof GoWebScanPipe
* @param  pipe              GoWebScanPipe object. 
* @param  task              Pointer to task to add.
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanPipe_AddTask(GoWebScanPipe pipe, GoWebScanPipeTask* task);

/**
* Adds a message pool to the pipe.
*
* @public                   @memberof GoWebScanPipe
* @param  pipe              GoWebScanPipe object. 
* @param  pool              Pointer to pool to add.
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanPipe_AddMsgPool(GoWebScanPipe pipe, GoWebScanPipeMsgPool* pool);

/**
* Initializes the pipe. Must be called after the thread count has been set and tasks have been added to the pipe.
*
* @public                   @memberof GoWebScanPipe
* @param  pipe              GoWebScanPipe object. 
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanPipe_Start(GoWebScanPipe pipe);

/**
* Receives and frees all messages exiting the pipe until the pipe is empty.
*
* @public                   @memberof GoWebScanPipe
* @param  pipe              GoWebScanPipe object. 
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanPipe_Clear(GoWebScanPipe pipe);

/**
* Dispatches a processing job (task + message) to the pipe. Sends the message to a task's message queue. 
* The task will submit the message to the pipe for processing if no other job is pending.
*
* @public                   @memberof GoWebScanPipe
* @param  pipe              GoWebScanPipe object. 
* @param  task              Task to receive message. 
* @param  msg               Message to enqueue for processing. 
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanPipe_Dispatch(GoWebScanPipe pipe, GoWebScanPipeTask task, GoWebScanPipeMsg msg);

/**
* Receives a completed processing job from the pipe. Retrieves the first out message from the outgoing queue
* and increases the reference count of this message.
*
* @public                   @memberof GoWebScanPipe
* @param  pipe              GoWebScanPipe object. 
* @param  msg               Receives processed GoWebScanPipeMsg object.
* @param  timeout           Timeout for waiting to receive a message (in microseconds). kINFINITE to wait indefinitely.
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanPipe_Receive(GoWebScanPipe pipe, GoWebScanPipeMsg* msg, k64u timeout);

/**
* Adds a completed message to the pipe's outgoing queue. Only used by GoWebScanPipeTask once processing is completed
* on a message.
*
* @public                   @memberof GoWebScanPipe
* @param  pipe              GoWebScanPipe object. 
* @param  msg               Completed message.
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanPipe_Emit(GoWebScanPipe pipe, GoWebScanPipeMsg msg);

/**
* Gets the current count of processing errors that have occurred in the pipe
*
* @public                   @memberof GoWebScanPipe
* @param  pipe              GoWebScanPipe object. 
* @return                   Error count.
*/
GoWebScanFx(kSize) GoWebScanPipe_ErrorCount(GoWebScanPipe pipe);

#include <GoWebScanSdk/GoWebScanPipe.x.h>

#endif