GoWebScan API
 All Classes Files Functions Variables Typedefs Macros Modules Pages
GoWebScanPipe.h
Go to the documentation of this file.
1 /**
2 * @file GoWebScanPipe.h
3 * @brief Declares a GoWebScanPipe object.
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_H
11 #define GO_WEB_SCAN_PIPE_H
12 
16 
17 kBeginHeader()
18 
19 /**
20 * @class GoWebScanPipe
21 * @extends kObject
22 * @ingroup GoWebScanSdk-Pipe
23 * @brief Represents a pipeline to run sequences of processing tasks concurrently. A GoWebScanPipe object
24 * coordinates executing GoWebScanPipeTask objects that have received a GoWebScanPipeMsg, and coordinates
25 * passing messages from task to task as processing steps execute. The pipe maintains a a priority
26 * queue of processing jobs, ordered by stage, and a thread pool to execute jobs. Higher priority
27 * jobs (higher stage number) are dispatched for processing before lower priority jobs.
28 */
29 typedef kObject GoWebScanPipe;
30 
31 // Forward declaration
33 
34 /** Defines the signature of the handler used by tasks to receive a message from the pipe. */
35 typedef kStatus(kCall *GoWebScanPipeSendFx)(kPointer context, GoWebScanPipeMsg msg);
36 
37 /**
38 * Constructs a GoWebScanPipe object.
39 *
40 * @public @memberof GoWebScanPipe
41 * @param pipe Receives the constructed GoWebScanPipe object.
42 * @param allocator Memory allocator (or kNULL for default).
43 * @return Operation status.
44 */
45 GoWebScanFx(kStatus) GoWebScanPipe_Construct(GoWebScanPipe* pipe, kAlloc allocator);
46 
47 /**
48 * Sets the number of threads to be used by the pipe. If not set, the threadcount will
49 * default to the maximum number of processors available in the host.
50 *
51 * @public @memberof GoWebScanPipe
52 * @param pipe GoWebScanPipe object.
53 * @param count Thread count.
54 * @return Operation status.
55 */
56 GoWebScanFx(kStatus) GoWebScanPipe_SetThreadCount(GoWebScanPipe pipe, kSize count);
57 
58 /**
59 * Gets the number of threads to be used by the pipe
60 *
61 * @public @memberof GoWebScanPipe
62 * @param pipe GoWebScanPipe object.
63 * @return Thread count.
64 */
65 GoWebScanFx(kSize) GoWebScanPipe_ThreadCount(GoWebScanPipe pipe);
66 
67 /**
68 * Adds a task to the pipe.
69 *
70 * @public @memberof GoWebScanPipe
71 * @param pipe GoWebScanPipe object.
72 * @param task Pointer to task to add.
73 * @return Operation status.
74 */
75 GoWebScanFx(kStatus) GoWebScanPipe_AddTask(GoWebScanPipe pipe, GoWebScanPipeTask* task);
76 
77 /**
78 * Adds a message pool to the pipe.
79 *
80 * @public @memberof GoWebScanPipe
81 * @param pipe GoWebScanPipe object.
82 * @param pool Pointer to pool to add.
83 * @return Operation status.
84 */
85 GoWebScanFx(kStatus) GoWebScanPipe_AddMsgPool(GoWebScanPipe pipe, GoWebScanPipeMsgPool* pool);
86 
87 /**
88 * Initializes the pipe. Must be called after the thread count has been set and tasks have been added to the pipe.
89 *
90 * @public @memberof GoWebScanPipe
91 * @param pipe GoWebScanPipe object.
92 * @return Operation status.
93 */
94 GoWebScanFx(kStatus) GoWebScanPipe_Start(GoWebScanPipe pipe);
95 
96 /**
97 * Receives and frees all messages exiting the pipe until the pipe is empty.
98 *
99 * @public @memberof GoWebScanPipe
100 * @param pipe GoWebScanPipe object.
101 * @return Operation status.
102 */
103 GoWebScanFx(kStatus) GoWebScanPipe_Clear(GoWebScanPipe pipe);
104 
105 /**
106 * Dispatches a processing job (task + message) to the pipe. Sends the message to a task's message queue.
107 * The task will submit the message to the pipe for processing if no other job is pending.
108 *
109 * @public @memberof GoWebScanPipe
110 * @param pipe GoWebScanPipe object.
111 * @param task Task to receive message.
112 * @param msg Message to enqueue for processing.
113 * @return Operation status.
114 */
115 GoWebScanFx(kStatus) GoWebScanPipe_Dispatch(GoWebScanPipe pipe, GoWebScanPipeTask task, GoWebScanPipeMsg msg);
116 
117 /**
118 * Receives a completed processing job from the pipe. Retrieves the first out message from the outgoing queue
119 * and increases the reference count of this message.
120 *
121 * @public @memberof GoWebScanPipe
122 * @param pipe GoWebScanPipe object.
123 * @param msg Receives processed GoWebScanPipeMsg object.
124 * @param timeout Timeout for waiting to receive a message (in microseconds). kINFINITE to wait indefinetely
125 * @return Operation status.
126 */
127 GoWebScanFx(kStatus) GoWebScanPipe_Receive(GoWebScanPipe pipe, GoWebScanPipeMsg* msg, k64u timeout);
128 
129 /**
130 * Adds a completed message to the pipe's outgoing queue. Only used by GoWebScanPipeTask once processing is completed
131 * on a message.
132 *
133 * @public @memberof GoWebScanPipe
134 * @param pipe GoWebScanPipe object.
135 * @param msg Completed message.
136 * @return Operation status.
137 */
138 GoWebScanFx(kStatus) GoWebScanPipe_Emit(GoWebScanPipe pipe, GoWebScanPipeMsg msg);
139 
140 /**
141 * Gets the current count of processing errors that have occurred in the pipe
142 *
143 * @public @memberof GoWebScanPipe
144 * @param pipe GoWebScanPipe object.
145 * @return Error count.
146 */
147 GoWebScanFx(kSize) GoWebScanPipe_ErrorCount(GoWebScanPipe pipe);
148 
149 kEndHeader()
150 #include <GoWebScanSdk/GoWebScanPipe.x.h>
151 
152 #endif
153 
kStatus(kCall * GoWebScanPipeSendFx)(kPointer context, GoWebScanPipeMsg msg)
Defines the signature of the handler used by tasks to receive a message from the pipe.
Definition: GoWebScanPipe.h:35
kStatus GoWebScanPipe_AddMsgPool(GoWebScanPipe pipe, GoWebScanPipeMsgPool *pool)
Adds a message pool to the pipe.
kSize GoWebScanPipe_ThreadCount(GoWebScanPipe pipe)
Gets the number of threads to be used by the pipe.
kStatus GoWebScanPipe_AddTask(GoWebScanPipe pipe, GoWebScanPipeTask *task)
Adds a task to the pipe.
kStatus GoWebScanPipe_Emit(GoWebScanPipe pipe, GoWebScanPipeMsg msg)
Adds a completed message to the pipe's outgoing queue.
Declares the GoWebScanPipeMsg class.
Declares the GoWebScanPipeMsgPool class.
kStatus GoWebScanPipe_SetThreadCount(GoWebScanPipe pipe, kSize count)
Sets the number of threads to be used by the pipe.
kStatus GoWebScanPipe_Dispatch(GoWebScanPipe pipe, GoWebScanPipeTask task, GoWebScanPipeMsg msg)
Dispatches a processing job (task + message) to the pipe.
Essential GoWebScan declarations.
kStatus GoWebScanPipe_Construct(GoWebScanPipe *pipe, kAlloc allocator)
Constructs a GoWebScanPipe object.
kStatus GoWebScanPipe_Clear(GoWebScanPipe pipe)
Receives and frees all messages exiting the pipe until the pipe is empty.
Represents a processing task for the GoWebScanPipe class. Each GoWebScanPipeTask maintains a FIFO que...
kStatus GoWebScanPipe_Receive(GoWebScanPipe pipe, GoWebScanPipeMsg *msg, k64u timeout)
Receives a completed processing job from the pipe.
Represents a pipeline to run sequences of processing tasks concurrently. A GoWebScanPipe object coord...
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 GoWebScanPipe_Start(GoWebScanPipe pipe)
Initializes the pipe.
kSize GoWebScanPipe_ErrorCount(GoWebScanPipe pipe)
Gets the current count of processing errors that have occurred in the pipe.