GoWebScanPipeMsgPool.h

Go to the documentation of this file.

/**
* @file    GoWebScanPipeMsgPool.h
* @brief   Declares the GoWebScanPipeMsgPool 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_MSG_POOL_H
#define GO_WEB_SCAN_PIPE_MSG_POOL_H

#include <GoWebScanSdk/GoWebScanSdkDef.h>

/**
* @class   GoWebScanPipeMsgPool
* @extends kObject
* @ingroup GoWebScanSdk-Pipe
* @brief   Represents a pool of GoWebScanPipeMsg objects. The pool allocates GoWebScanPipeMsg objects 
*          with a default reference count of 1. Messages are recycled to the pool's free list when the 
*          message's reference count reaches 0. A GoWebScanPipeMsgPool can only contain GoWebScanPipeMsg
*          objects of the same GoWebScanMsgType
*/
typedef kObject GoWebScanPipeMsgPool; 

// Forward declaration
typedef kObject GoWebScanPipeMsg;

/** Defines the signature for the memory allocation handler for a message. */
typedef kStatus(kCall *GoWebScanPipeMsgPoolAllocFx)(kPointer context, GoWebScanPipeMsgPool pool, GoWebScanPipeMsg* msg);

/** Defines the signature for the memory recycling handler for a message. */
typedef kStatus(kCall *GoWebScanPipeMsgPoolFreeFx)(GoWebScanPipeMsg msg);

/** Defines the signature for the message destruction handler. */
typedef kStatus(kCall *GoWebScanPipeMsgPoolDestroyFx)(GoWebScanPipeMsg msg);

/** Defines the signature for the message size handler. */
typedef kSize(kCall *GoWebScanPipeMsgPoolSizeFx)(GoWebScanPipeMsg msg);

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

/**
* Sets the message allocation callback function
*
* @public                   @memberof GoWebScanPipeMsgPool
* @param  pool              GoWebScanPipeMsgPool object.
* @param  alloc             Message allocation callback function
* @param  receiver          Receiver argument for callback.
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanPipeMsgPool_SetAllocHandler(GoWebScanPipeMsgPool pool, GoWebScanPipeMsgPoolAllocFx alloc, kPointer receiver);

/**
* Sets the callback function for the message's data buffer size (in bytes).
*
* @public                   @memberof GoWebScanPipeMsgPool
* @param  pool              GoWebScanPipeMsgPool object.
* @param  size              Message size callback function
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanPipeMsgPool_SetSizeHandler(GoWebScanPipeMsgPool pool, GoWebScanPipeMsgPoolSizeFx size);

/**
* Sets the callback function to recycle memory allocated for a message
*
* @public                   @memberof GoWebScanPipeMsgPool
* @param  pool              GoWebScanPipeMsgPool object.
* @param  free              Free message callback function
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanPipeMsgPool_SetFreeHandler(GoWebScanPipeMsgPool pool, GoWebScanPipeMsgPoolFreeFx free);

/**
* Sets the message destruction callback function
*
* @public                   @memberof GoWebScanPipeMsgPool
* @param  pool              GoWebScanPipeMsgPool object.
* @param  destroy           Message destruction callback function
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanPipeMsgPool_SetDestroyHandler(GoWebScanPipeMsgPool pool, GoWebScanPipeMsgPoolDestroyFx destroy);

/**
* Allocates a GoWebScanPipeMsg object and adds it to the pool's allocated list. Memory is recycled from the 
* pool's free list if available.
*
* @public                   @memberof GoWebScanPipeMsgPool
* @param  pool              GoWebScanPipeMsgPool object.
* @param  msg               Receives the allocated GoWebScanPipeMsg object. 
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanPipeMsgPool_Alloc(GoWebScanPipeMsgPool pool, GoWebScanPipeMsg* msg);

/**
* Gets the count of the pool's allocated list.
*
* @public                   @memberof GoWebScanPipeMsgPool
* @param  pool              GoWebScanPipeMsgPool object.
* @return                   Count of pool's allocated list
*/
GoWebScanFx(kSize) GoWebScanPipeMsgPool_AllocCount(GoWebScanPipeMsgPool pool);

/**
* Gets the count of the pool's free list.
*
* @public                   @memberof GoWebScanPipeMsgPool
* @param  pool              GoWebScanPipeMsgPool object.
* @return                   Count of pool's free list
*/
GoWebScanFx(kSize) GoWebScanPipeMsgPool_FreeCount(GoWebScanPipeMsgPool pool);

#include <GoWebScanSdk/GoWebScanPipeMsgPool.x.h>

#endif