PIP 5.6.1
Platform-Independent Primitives
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
PIPipelineThread< Tin, Tout > Class Template Referenceabstract

Thread-based pipeline template class for multi-stage data processing. More...

#include <pipipelinethread.h>

Inheritance diagram for PIPipelineThread< Tin, Tout >:
Inheritance graph
[legend]

Public Member Functions

 PIPipelineThread ()
 Constructs pipeline thread.
 
 ~PIPipelineThread ()
 Stops the stage thread and may terminate it forcibly if it does not finish in time.
 
template<typename T >
void connectTo (PIPipelineThread< Tout, T > *next)
 Connects to next pipeline stage via event notification.
 
void enqueue (const Tin &v, bool wait=false)
 Enqueue data for processing.
 
const ullong * counterPtr () const
 Returns pointer to counter.
 
ullong counter () const
 Returns items processed counter.
 
bool isEmpty ()
 Returns whether the input queue is empty.
 
int queSize ()
 Returns the current input queue size.
 
void clear ()
 Clear input queue.
 
void stopCalc (int wait_delay=100)
 Stops calculation and waits for thread finish. More...
 
Tout getLast ()
 Returns a copy of the last successfully calculated output. More...
 
uint maxQueSize ()
 Returns the configured input queue limit. More...
 
void setMaxQueSize (uint count)
 Sets the input queue limit. More...
 
bool isWaitNextPipe ()
 Returns if waiting for next pipeline stage.
 
void setWaitNextPipe (bool wait)
 Sets whether to wait for next pipeline stage. More...
 
- Public Member Functions inherited from PIThread
 PIThread (void *data, ThreadFunc func, bool startNow=false, PISystemTime loop_delay={})
 Constructs a thread with user data, callback and optional immediate start.
 
 PIThread (std::function< void()> func, bool startNow=false, PISystemTime loop_delay={})
 Constructs a thread with a callback without custom data.
 
 PIThread (bool startNow=false, PISystemTime loop_delay={})
 Constructs a subclass-oriented thread with an optional loop delay.
 
virtual ~PIThread ()
 Destroys the thread object. If it is still running, destruction forces termination.
 
bool start ()
 Starts the thread with the stored callback and loop delay.
 
bool start (PISystemTime loop_delay)
 Stores a new loop delay and starts the thread.
 
bool start (ThreadFunc func)
 Stores a callback and starts the thread.
 
bool start (ThreadFunc func, PISystemTime loop_delay)
 Stores a callback and loop delay, then starts the thread.
 
bool start (std::function< void()> func)
 Stores a lambda callback and starts the thread.
 
bool start (std::function< void()> func, PISystemTime loop_delay)
 Stores a lambda callback and loop delay, then starts the thread.
 
bool startOnce ()
 Starts a one-shot thread without the repeating loop. More...
 
bool startOnce (ThreadFunc func)
 Stores a callback and starts one-shot execution. More...
 
bool startOnce (std::function< void()> func)
 Stores a lambda callback and starts one-shot execution.
 
bool stopAndWait (int timeout_ms) DEPRECATEDM("use stopAndWait(PISystemTime)")
 Deprecated overload of stopAndWait() that accepts milliseconds.
 
bool stopAndWait (PISystemTime timeout={})
 Requests stop and waits for thread completion. Returns false if the timeout expires.
 
void setData (void *d)
 Sets the data pointer passed to ThreadFunc callbacks.
 
void setSlot (ThreadFunc func)
 Sets the callback executed after each run() pass.
 
void setSlot (std::function< void()> func)
 Sets a lambda callback executed after each run() pass.
 
void setPriority (PIThread::Priority prior)
 Sets the priority hint. If the thread is already running, applies it immediately.
 
void * data () const
 Returns the data pointer passed to ThreadFunc callbacks.
 
PIThread::Priority priority () const
 Returns the configured priority hint.
 
bool isRunning () const
 Returns whether the thread is currently running.
 
bool isStopping () const
 Returns whether stop has been requested and the thread is still finishing.
 
bool waitForStart (PISystemTime timeout={})
 Waits until the thread starts. Returns false if the timeout expires first.
 
bool waitForStart (int timeout_msecs) DEPRECATEDM("use waitForStart(PISystemTime)")
 Deprecated overload of waitForStart() that accepts milliseconds. More...
 
bool waitForFinish (PISystemTime timeout={})
 Waits for thread completion. Returns false if the timeout expires first.
 
bool waitForFinish (int timeout_msecs) DEPRECATEDM("use waitForFinish(PISystemTime)")
 Deprecated overload of waitForFinish() that accepts milliseconds. More...
 
void needLockRun (bool need)
 Enables locking of the internal mutex around begin(), run(), callbacks and end().
 
PIMutexmutex () const
 Returns the internal mutex used by lock(), unlock() and needLockRun().
 
llong tid () const
 Returns the system thread identifier, or -1 when the thread is not running.
 
void stop ()
 Requests graceful thread shutdown. More...
 
void terminate ()
 Forces thread termination. Use only as a last resort. More...
 
void lock () const
 Locks the internal mutex.
 
void unlock () const
 Unlocks the internal mutex.
 
void started ()
 Raised after the thread has started.
 
void stopped ()
 Raised when thread shutdown begins.
 
- Public Member Functions inherited from PIObject
 PIObject (const PIString &name=PIString())
 Constructs an object and initializes its name property.
 
virtual ~PIObject ()
 Destroys the object, raises deleted() and disconnects it from the event graph.
 
PIString name () const
 Returns the name property of this object.
 
virtual const char * className () const
 Returns the registered class name of this object.
 
virtual uint classNameID () const
 Returns the hash of className().
 
virtual const char * parentClassName () const
 Returns the registered parent class name, or an empty string for the root.
 
bool debug () const
 Returns whether piCoutObj output is enabled for this object.
 
void setName (const PIString &name)
 Sets the name property of this object.
 
void setDebug (bool debug)
 Enables or disables piCoutObj output for this object.
 
PIVariant property (const char *name) const
 Returns the property with name "name".
 
void setProperty (const char *name, const PIVariant &value)
 Sets the property "name" to "value" and creates it if needed. More...
 
bool isPropertyExists (const char *name) const
 Returns whether the property "name" exists.
 
void setThreadSafe (bool yes)
 Enables or disables the internal object mutex during handler execution. More...
 
bool isThreadSafe () const
 Returns whether the internal object mutex is enabled for handler execution.
 
bool execute (const PIString &method, const PIVector< PIVariantSimple > &vl)
 Executes a registered method or handler method by name with the supplied arguments. More...
 
bool execute (const PIString &method)
 Overload of execute() for a method without arguments.
 
bool execute (const PIString &method, const PIVariantSimple &v0)
 Overload of execute() for one argument.
 
bool execute (const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1)
 Overload of execute() for two arguments.
 
bool execute (const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1, const PIVariantSimple &v2)
 Overload of execute() for three arguments.
 
bool execute (const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1, const PIVariantSimple &v2, const PIVariantSimple &v3)
 Overload of execute() for four arguments.
 
bool executeQueued (PIObject *performer, const PIString &method, const PIVector< PIVariantSimple > &vl)
 Queues execution of a registered method on the performer object. More...
 
bool executeQueued (PIObject *performer, const PIString &method)
 Overload of executeQueued() for a method without arguments.
 
bool executeQueued (PIObject *performer, const PIString &method, const PIVariantSimple &v0)
 Overload of executeQueued() for one argument.
 
bool executeQueued (PIObject *performer, const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1)
 Overload of executeQueued() for two arguments.
 
bool executeQueued (PIObject *performer, const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1, const PIVariantSimple &v2)
 Overload of executeQueued() for three arguments.
 
bool executeQueued (PIObject *performer, const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1, const PIVariantSimple &v2, const PIVariantSimple &v3)
 Overload of executeQueued() for four arguments.
 
void dump (const PIString &line_prefix=PIString()) const
 Dumps object diagnostics to the project output stream.
 
PIStringList scopeList () const
 Returns the registered inheritance scope of this object, including its own class.
 
PIStringList methodsEH () const
 Returns full signatures of all registered event and handler methods for this class scope.
 
bool isMethodEHContains (const PIString &name) const
 Returns whether a registered event or handler method with this name exists.
 
PIString methodEHArguments (const PIString &name) const
 Returns the comma-separated argument type list of a registered method.
 
PIString methodEHFullFormat (const PIString &name) const
 Returns the full registered signature of a method.
 
PIString methodEHFromAddr (const void *addr) const
 Returns the registered method name for the specified entry-point address.
 
void piDisconnect (const PIString &sig, PIObject *dest, void *ev_h)
 Disconnects this source object from a specific destination handler for event "sig".
 
void piDisconnect (const PIString &sig, PIObject *dest)
 Disconnects this source object from all connections of event "sig" to destination object "dest".
 
void piDisconnect (const PIString &sig)
 Disconnects this source object from all connections of event "sig".
 
bool isPIObject () const
 Returns whether this pointer still refers to a live PIObject instance.
 
template<typename T >
bool isTypeOf () const
 Returns whether this object belongs to class "T" or one of its registered descendants.
 
template<typename T >
T * cast () const
 Returns this object cast to "T" when isTypeOf<T>() succeeds, otherwise nullptr.
 
void callQueuedEvents ()
 Executes all queued deliveries posted to this performer object.
 
bool maybeCallQueuedEvents ()
 Executes queued deliveries only when this object was used as a performer. More...
 
void deleteLater ()
 Schedules the object for deferred deletion. More...
 
void deleted (PIObject *o)
 Raised immediately before object destruction. More...
 

Protected Member Functions

virtual Tout calc (Tin &v, bool &ok)=0
 Calculates one output from queued input v. More...
 
- Protected Member Functions inherited from PIThread
virtual void begin ()
 Virtual method executed once after the system thread starts and before started().
 
virtual void run ()
 Virtual method executed on each loop iteration until stop is requested.
 
virtual void end ()
 Virtual method executed once during thread shutdown after stopped().
 
- Protected Member Functions inherited from PIObject
PIObjectemitter () const
 Returns the source object that raised the current event. More...
 
virtual void propertyChanged (const char *name)
 Virtual method called after property "name" has been changed by setProperty().
 

Protected Attributes

uint max_size
 Maximum queue size (0 means unlimited)
 

Handlers

void enqueue (const Tin &v, bool wait, bool *overload)
 Event handler for data enqueue. More...
 

Events

void calculated (const Tout &v, bool wait, bool *overload)
 Emitted when processing result is ready. More...
 

Additional Inherited Members

- Public Types inherited from PIThread
enum  Priority {
  piLowerst , piLow , piNormal , piHigh ,
  piHighest
}
 Thread priority hint. More...
 
- Static Public Member Functions inherited from PIThread
static void runOnce (PIObject *object, const char *handler, const PIString &name=PIString())
 Creates a temporary thread and invokes handler handler of object object on it. More...
 
static void runOnce (std::function< void()> func, const PIString &name=PIString())
 Creates a temporary thread and runs lambda expression func on it. More...
 
- Static Public Member Functions inherited from PIObject
static bool execute (PIObject *o, const PIString &method, const PIVector< PIVariantSimple > &vl)
 Static convenience wrapper for execute().
 
static bool execute (PIObject *o, const PIString &method)
 Static overload of execute() without arguments.
 
static bool execute (PIObject *o, const PIString &method, const PIVariantSimple &v0)
 Static overload of execute() for one argument.
 
static bool execute (PIObject *o, const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1)
 Static overload of execute() for two arguments.
 
static bool execute (PIObject *o, const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1, const PIVariantSimple &v2)
 Static overload of execute() for three arguments.
 
static bool execute (PIObject *o, const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1, const PIVariantSimple &v2, const PIVariantSimple &v3)
 Static overload of execute() for four arguments.
 
static bool executeQueued (PIObject *o, PIObject *performer, const PIString &method, const PIVector< PIVariantSimple > &vl)
 Static convenience wrapper for executeQueued().
 
static bool executeQueued (PIObject *o, PIObject *performer, const PIString &method)
 Static overload of executeQueued() without arguments.
 
static bool executeQueued (PIObject *o, PIObject *performer, const PIString &method, const PIVariantSimple &v0)
 Static overload of executeQueued() for one argument.
 
static bool executeQueued (PIObject *o, PIObject *performer, const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1)
 Static overload of executeQueued() for two arguments.
 
static bool executeQueued (PIObject *o, PIObject *performer, const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1, const PIVariantSimple &v2)
 Static overload of executeQueued() for three arguments.
 
static bool executeQueued (PIObject *o, PIObject *performer, const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1, const PIVariantSimple &v2, const PIVariantSimple &v3)
 Static overload of executeQueued() for four arguments.
 
static PIObject::Connection piConnect (PIObject *src, const PIString &sig, PIObject *dest_o, void *dest, void *ev_h, void *e_h, int args, const char *loc)
 Low-level direct connection helper behind the legacy CONNECT* macros.
 
static PIObject::Connection piConnectU (PIObject *src, const PIString &sig, PIObject *dest_o, void *dest, const PIString &hname, const char *loc, PIObject *performer=0)
 Low-level name-based connection helper behind CONNECTU() and CONNECTU_QUEUED().
 
static PIObject::Connection piConnectLS (PIObject *src, const PIString &sig, std::function< void()> *f, const char *loc)
 Low-level helper that connects an event to a lambda or functor wrapper.
 
static void piDisconnect (PIObject *src, const PIString &sig, PIObject *dest, void *ev_h)
 Disconnects source object "src" from a specific destination handler for event "sig".
 
static void piDisconnect (PIObject *src, const PIString &sig, PIObject *dest)
 Disconnects source object "src" from all connections of event "sig" to destination object "dest".
 
static void piDisconnect (PIObject *src, const PIString &sig)
 Disconnects source object "src" from all connections of event "sig".
 
static void raiseEvent (PIObject *sender, const uint eventID)
 Internal event delivery helper for registered events without arguments.
 
template<typename T0 >
static void raiseEvent (PIObject *sender, const uint eventID, const T0 &v0=T0())
 Internal event delivery helper for registered events with one argument.
 
template<typename T0 , typename T1 >
static void raiseEvent (PIObject *sender, const uint eventID, const T0 &v0=T0(), const T1 &v1=T1())
 Internal event delivery helper for registered events with two arguments.
 
template<typename T0 , typename T1 , typename T2 >
static void raiseEvent (PIObject *sender, const uint eventID, const T0 &v0=T0(), const T1 &v1=T1(), const T2 &v2=T2())
 Internal event delivery helper for registered events with three arguments.
 
template<typename T0 , typename T1 , typename T2 , typename T3 >
static void raiseEvent (PIObject *sender, const uint eventID, const T0 &v0=T0(), const T1 &v1=T1(), const T2 &v2=T2(), const T3 &v3=T3())
 Internal event delivery helper for registered events with four arguments.
 
static PIObjectfindByName (const PIString &name)
 Returns the first live object with name "name", or nullptr.
 
static bool isPIObject (const PIObject *o)
 Returns whether "o" points to a live PIObject instance.
 
static bool isPIObject (const void *o)
 Overload of isPIObject() for an untyped pointer.
 
template<typename T >
static bool isTypeOf (const PIObject *o)
 Returns whether "o" belongs to class "T" or one of its registered descendants.
 
template<typename T >
static bool isTypeOf (const void *o)
 Overload of isTypeOf() for an untyped pointer.
 
static PIString simplifyType (const char *a, bool readable=true)
 Simplifies a C++ type spelling for registered-method metadata.
 

Detailed Description

template<typename Tin, typename Tout>
class PIPipelineThread< Tin, Tout >

Thread-based pipeline template class for multi-stage data processing.

Pipeline thread template class for processing data through multiple stages in separate threads.

Member Function Documentation

◆ enqueue()

template<typename Tin , typename Tout >
void PIPipelineThread< Tin, Tout >::enqueue ( const Tin &  v,
bool  wait,
bool *  overload 
)
inline

Event handler for data enqueue.

For bounded queues, wait decides whether to block until space is available or to drop the item immediately. Если overload не равен null, он получает значение true, когда элемент отклонен из-за переполнения очереди.

◆ calculated()

template<typename Tin , typename Tout >
void PIPipelineThread< Tin, Tout >::calculated ( const Tout &  v,
bool  wait,
bool *  overload 
)

Emitted when processing result is ready.

Raised after calc() succeeds.

Note
The wait flag is propagated to a downstream stage and does not affect this stage's own queue.

◆ stopCalc()

template<typename Tin , typename Tout >
void PIPipelineThread< Tin, Tout >::stopCalc ( int  wait_delay = 100)
inline

Stops calculation and waits for thread finish.

Note
If the stage does not stop within wait_delay, it may be terminated forcibly.

◆ getLast()

template<typename Tin , typename Tout >
Tout PIPipelineThread< Tin, Tout >::getLast ( )
inline

Returns a copy of the last successfully calculated output.

Note
This snapshot is separate from the input queue.

◆ maxQueSize()

template<typename Tin , typename Tout >
uint PIPipelineThread< Tin, Tout >::maxQueSize ( )
inline

Returns the configured input queue limit.

Note
Value 0 means the queue is unbounded.

◆ setMaxQueSize()

template<typename Tin , typename Tout >
void PIPipelineThread< Tin, Tout >::setMaxQueSize ( uint  count)
inline

Sets the input queue limit.

Note
Value 0 removes the limit. If the queue already exceeds the new limit, it is resized immediately.

◆ setWaitNextPipe()

template<typename Tin , typename Tout >
void PIPipelineThread< Tin, Tout >::setWaitNextPipe ( bool  wait)
inline

Sets whether to wait for next pipeline stage.

Sets whether the calculated() signal requests waiting in the downstream stage.

Note
This flag only affects downstream propagation and does not change how this stage accepts input.

◆ calc()

template<typename Tin , typename Tout >
virtual Tout PIPipelineThread< Tin, Tout >::calc ( Tin &  v,
bool &  ok 
)
protectedpure virtual

Calculates one output from queued input v.

Note
Leave ok equal to true to publish the result, or set it to false to drop this input without forwarding.