GoWebScan API
 All Classes Files Functions Variables Typedefs Macros Modules Pages
GoWebScanPipeMsgPool.h
Go to the documentation of this file.
1 /**
2 * @file GoWebScanPipeMsgPool.h
3 * @brief Declares the GoWebScanPipeMsgPool class.
4 *
5 * @internal
6 * Copyright (C) 2017-2018 by LMI Technologies Inc.
7 * Licensed under the MIT License.
8 * Redistributed files must retain the above copyright notice.
9 */
10 #ifndef GO_WEB_SCAN_PIPE_MSG_POOL_H
11 #define GO_WEB_SCAN_PIPE_MSG_POOL_H
12 
14 
15 kBeginHeader()
16 
17 /**
18 * @class GoWebScanPipeMsgPool
19 * @extends kObject
20 * @ingroup GoWebScanSdk-Pipe
21 * @brief Represents a pool of GoWebScanPipeMsg objects. The pool allocates GoWebScanPipeMsg objects
22 * with a default reference count of 1. Messages are recycled to the pool's free list when the
23 * message's reference count reaches 0. A GoWebScanPipeMsgPool can only contain GoWebScanPipeMsg
24 * objects of the same GoWebScanMsgType
25 */
27 
28 // Forward declaration
30 
31 /** Defines the signature for the memory allocation handler for a message. */
32 typedef kStatus(kCall *GoWebScanPipeMsgPoolAllocFx)(kPointer context, GoWebScanPipeMsgPool pool, GoWebScanPipeMsg* msg);
33 
34 /** Defines the signature for the memory recycling handler for a message. */
35 typedef kStatus(kCall *GoWebScanPipeMsgPoolFreeFx)(GoWebScanPipeMsg msg);
36 
37 /** Defines the signature for the message destruction handler. */
38 typedef kStatus(kCall *GoWebScanPipeMsgPoolDestroyFx)(GoWebScanPipeMsg msg);
39 
40 /** Defines the signature for the message size handler. */
41 typedef kSize(kCall *GoWebScanPipeMsgPoolSizeFx)(GoWebScanPipeMsg msg);
42 
43 /**
44 * Constructs a GoWebScanPipeMsgPool object.
45 *
46 * @public @memberof GoWebScanPipeMsgPool
47 * @param pool Receives the constructed GoWebScanPipeMsgPool object.
48 * @param allocator Memory allocator (or kNULL for default).
49 * @return Operation status.
50 */
51 GoWebScanFx(kStatus) GoWebScanPipeMsgPool_Construct(GoWebScanPipeMsgPool* pool, kAlloc allocator);
52 
53 /**
54 * Sets the message allocation callback function
55 *
56 * @public @memberof GoWebScanPipeMsgPool
57 * @param pool GoWebScanPipeMsgPool object.
58 * @param alloc Message allocation callback function
59 * @param receiver Receiver argument for callback.
60 * @return Operation status.
61 */
62 GoWebScanFx(kStatus) GoWebScanPipeMsgPool_SetAllocHandler(GoWebScanPipeMsgPool pool, GoWebScanPipeMsgPoolAllocFx alloc, kPointer receiver);
63 
64 /**
65 * Sets the callback function for the message's data buffer size (in bytes).
66 *
67 * @public @memberof GoWebScanPipeMsgPool
68 * @param pool GoWebScanPipeMsgPool object.
69 * @param size Message size callback function
70 * @return Operation status.
71 */
72 GoWebScanFx(kStatus) GoWebScanPipeMsgPool_SetSizeHandler(GoWebScanPipeMsgPool pool, GoWebScanPipeMsgPoolSizeFx size);
73 
74 /**
75 * Sets the callback function to recycle memory allocated for a message
76 *
77 * @public @memberof GoWebScanPipeMsgPool
78 * @param pool GoWebScanPipeMsgPool object.
79 * @param free Free message callback function
80 * @return Operation status.
81 */
82 GoWebScanFx(kStatus) GoWebScanPipeMsgPool_SetFreeHandler(GoWebScanPipeMsgPool pool, GoWebScanPipeMsgPoolFreeFx free);
83 
84 /**
85 * Sets the message destruction callback function
86 *
87 * @public @memberof GoWebScanPipeMsgPool
88 * @param pool GoWebScanPipeMsgPool object.
89 * @param destroy Message destruction callback function
90 * @return Operation status.
91 */
92 GoWebScanFx(kStatus) GoWebScanPipeMsgPool_SetDestroyHandler(GoWebScanPipeMsgPool pool, GoWebScanPipeMsgPoolDestroyFx destroy);
93 
94 /**
95 * Allocates a GoWebScanPipeMsg object and adds it to the pool's allocated list. Memory is recycled from the
96 * pool's free list if available.
97 *
98 * @public @memberof GoWebScanPipeMsgPool
99 * @param pool GoWebScanPipeMsgPool object.
100 * @param msg Receives the allocated GoWebScanPipeMsg object.
101 * @return Operation status.
102 */
103 GoWebScanFx(kStatus) GoWebScanPipeMsgPool_Alloc(GoWebScanPipeMsgPool pool, GoWebScanPipeMsg* msg);
104 
105 /**
106 * Gets the count of the pool's allocated list.
107 *
108 * @public @memberof GoWebScanPipeMsgPool
109 * @param pool GoWebScanPipeMsgPool object.
110 * @return Count of pool's allocated list
111 */
112 GoWebScanFx(kSize) GoWebScanPipeMsgPool_AllocCount(GoWebScanPipeMsgPool pool);
113 
114 /**
115 * Gets the count of the pool's free list.
116 *
117 * @public @memberof GoWebScanPipeMsgPool
118 * @param pool GoWebScanPipeMsgPool object.
119 * @return Count of pool's free list
120 */
121 GoWebScanFx(kSize) GoWebScanPipeMsgPool_FreeCount(GoWebScanPipeMsgPool pool);
122 
123 kEndHeader()
124 
125 #include <GoWebScanSdk/GoWebScanPipeMsgPool.x.h>
126 
127 #endif
128 
kStatus(kCall * GoWebScanPipeMsgPoolDestroyFx)(GoWebScanPipeMsg msg)
Defines the signature for the message destruction handler.
Definition: GoWebScanPipeMsgPool.h:38
kStatus GoWebScanPipeMsgPool_Construct(GoWebScanPipeMsgPool *pool, kAlloc allocator)
Constructs a GoWebScanPipeMsgPool object.
kStatus GoWebScanPipeMsgPool_SetSizeHandler(GoWebScanPipeMsgPool pool, GoWebScanPipeMsgPoolSizeFx size)
Sets the callback function for the message's data buffer size (in bytes).
kSize GoWebScanPipeMsgPool_AllocCount(GoWebScanPipeMsgPool pool)
Gets the count of the pool's allocated list.
Essential GoWebScan declarations.
kStatus(kCall * GoWebScanPipeMsgPoolAllocFx)(kPointer context, GoWebScanPipeMsgPool pool, GoWebScanPipeMsg *msg)
Defines the signature for the memory allocation handler for a message.
Definition: GoWebScanPipeMsgPool.h:32
kStatus GoWebScanPipeMsgPool_SetAllocHandler(GoWebScanPipeMsgPool pool, GoWebScanPipeMsgPoolAllocFx alloc, kPointer receiver)
Sets the message allocation callback function.
kStatus(kCall * GoWebScanPipeMsgPoolFreeFx)(GoWebScanPipeMsg msg)
Defines the signature for the memory recycling handler for a message.
Definition: GoWebScanPipeMsgPool.h:35
kStatus GoWebScanPipeMsgPool_SetFreeHandler(GoWebScanPipeMsgPool pool, GoWebScanPipeMsgPoolFreeFx free)
Sets the callback function to recycle memory allocated for a message.
kSize(kCall * GoWebScanPipeMsgPoolSizeFx)(GoWebScanPipeMsg msg)
Defines the signature for the message size handler.
Definition: GoWebScanPipeMsgPool.h:41
kSize GoWebScanPipeMsgPool_FreeCount(GoWebScanPipeMsgPool pool)
Gets the count of the pool's free list.
kStatus GoWebScanPipeMsgPool_Alloc(GoWebScanPipeMsgPool pool, GoWebScanPipeMsg *msg)
Allocates a GoWebScanPipeMsg object and adds it to the pool's allocated list.
Represents a pool of GoWebScanPipeMsg objects. The pool allocates GoWebScanPipeMsg objects with a def...
Base class for a msg that can be processed with a GoWebScanPipeTask and submitted to the GoWebScanPip...
kStatus GoWebScanPipeMsgPool_SetDestroyHandler(GoWebScanPipeMsgPool pool, GoWebScanPipeMsgPoolDestroyFx destroy)
Sets the message destruction callback function.