AxPipe::CPipe Class Reference

The generic pipe-segment as an abstract class. More...

#include <AxPipe.h>

Inheritance diagram for AxPipe::CPipe:

[legend]Collaboration diagram for AxPipe::CPipe:

[legend]List of all members.

Public Member Functions
	CPipe ()
	Initialize member variables.
	~CPipe ()
	Destruct the sink as well, depending.
CPipe *	Append (CSink *pSink)
	Append a section by pointer with auto deletion.
CPipe *	Append (CSink &sink)
	Append a section by reference.
void	Sync ()
	Ensure that all threads downstream are idle.
void	Open ()
	Utility function, call to open the pipe downstream for output.
void	Pump (CSeg *pSeg)
	Utility function, call typically from Out(), to send a segment downstream.
void	Flush ()
	Utility function, call to flush the pipe downstream.
void	Close ()
	Utility function, call to close the pipe downstream for output.
Protected Member Functions
void	Work ()
	Process one memory segment, possibly propagating.
void	AppendSink (CSink *pSink, bool fAutoDelete)
	Append a section by pointer.
CSeg *	GetSeg (size_t cb)
	Utility function, call if you think the next is a CSink that might give you an efficient segment.
void	Signal (void *vId, void *p)
	Out of band signalling downstream.
longlong	OutSizeMax ()
	Overrideable, Calculate the maximum size of the CSink.
CSeg *	OutGetSeg (size_t cb)
	Overrideable, Allocate a writeable CSeg, possibly optimized for the CSink.
bool	OutSignal (void *vId, void *p)
	Overrideable, Receive an out of band signal from upstream.
bool	OutOpen ()
	Overrideable, Open the data stream for processing.
bool	OutClose ()
	Overrideable, Output any final data, close and prepare for new Open().
void	OutSpecial (CSeg *pSeg)
	Overrideable, Process a special segment and send results downstream with Pump().
void	Out (CSeg *pSeg)=0
	Overrideable, Consume a segment and Pump() the processed result downstream.
Protected Attributes
CSink *	m_pSink
	Forward pointer to next section downstream.
Private Member Functions
void	DestructSink ()
	The actual destructor code.
Friends
class	CSplit
	CSplit needs private access.

---

Detailed Description

The generic pipe-segment as an abstract class.

All non CSink objects are derived from CPipe, push and pull model processing segments as well as CSource.

The minimum derived class overrides Out() and processes the CSeg provided, using the utility member function Pump() to send processed data downstream.

Definition at line 269 of file AxPipe.h.

---

Constructor & Destructor Documentation

AxPipe::CPipe::CPipe (   )

Initialize member variables. Do remember to only use default constructors in derived classes, and implement an Init() member if the class needs parameters for construction. The reason for this is the implementation of AxPipe::CThread as a template class. Definition at line 259 of file CPipe.cpp.

---

Member Function Documentation

CPipe * AxPipe::CPipe::Append (  CSink &  sink  )

Append a section by reference. Append the next section by providing a reference to an instance. See the corresponding pointer version for details. Sections appended by reference are never auto-delete'd. Parameters: sink  Reference to an instance of a CSink derived object. Returns: A pointer to 'this' CPipe Reimplemented in AxPipe::CSource. Definition at line 112 of file CPipe.cpp. References AppendSink().

CPipe * AxPipe::CPipe::Append (  CSink *  pSink  )

Append a section by pointer with auto deletion. Append the next section by providing a pointer to an instance. The chain of sections is scanned until it ends, and then the pointer to the segment is appended. Parameters: pSink  Pointer to an instance of a CSink derived object. Returns: A pointer to 'this' CPipe Reimplemented in AxPipe::CSource. Definition at line 102 of file CPipe.cpp. References AppendSink().

void AxPipe::CPipe::AppendSink (  CSink *  pSink, bool  fAutoDeleteSink )  [protected, virtual]

Append a section by pointer. Append the next section of the pipe, by providing a pointer to an instance. Do not call this directly, use CSource::Append(). Parameters: pSink  Pointer to an instance of a CSink derived object. fAutoDeleteSink  true if the object should be delete'd when the member upstream is delete'd. Reimplemented from AxPipe::CSink. Reimplemented in AxPipe::CSplit. Definition at line 88 of file CPipe.cpp. References AxPipe::CSink::AppendSink(), and m_pSink. Referenced by AxPipe::CSource::Append(), and Append().

void AxPipe::CPipe::DestructSink (   )  [private, virtual]

The actual destructor code. Destruct the chain, waiting for parts of it to finish and skipping parts that should not be auto-destructed. It will call delete for those sections that are marked for auto-destruction. It is called by the base class destructor. If you need further clean up during destruction do that in a virtual destructor. Only override this if m_pSink does not point to a CSink derived section to also include in the chain of destruction. Reimplemented from AxPipe::CSink. Reimplemented in AxPipe::CSplit. Definition at line 45 of file CPipe.cpp. References _T, ASSCHK, AxPipe::CSink::DestructSink(), AxPipe::CNoThread::m_fExit, m_pSink, and AxPipe::CNoThread::WaitForIdle().

void AxPipe::CPipe::Out (  CSeg *  pSeg  )  [protected, pure virtual]

Overrideable, Consume a segment and Pump() the processed result downstream. The provided segment is guaranteed to be non-NULL and non-zero-length Special CSeg's with a non-zero eSegType value will be sent to OutSpecial() instead. Out() must be implemented in derived classes, there is no default. Pump() is the normal method for sending processed data. Parameters: pSeg  A memory segment to process or consume. See also: Pump() Implements AxPipe::CSink. Implemented in AxPipe::CSplit, AxPipe::CSource, AxPipe::CFilter, AxPipe::Stock::CPipeFindSync, AxPipe::Stock::CPipeHMAC_SHA1< iBits >, AxPipe::Stock::CPipeInflate, and AxPipe::Stock::CPipeSHA1.

bool AxPipe::CPipe::OutClose (  void   )  [protected, virtual]

Overrideable, Output any final data, close and prepare for new Open(). The code should handle multiple (extra) calls to an already closed stream with no ill effects, i.e. silently ignore them. This default implementation returns true to enable propagation by the framework. Returns: true if the framework should propagate the Close() request downstream. Reimplemented from AxPipe::CSink. Reimplemented in AxPipe::CSplit, AxPipe::CFilter, AxPipe::CSourceMemFile, AxPipe::Stock::CPipeHMAC_SHA1< iBits >, AxPipe::Stock::CPipeInflate, and AxPipe::Stock::CPipeSHA1. Definition at line 240 of file CPipe.cpp.

CSeg * AxPipe::CPipe::OutGetSeg (  size_t  cb  )  [protected, virtual]

Overrideable, Allocate a writeable CSeg, possibly optimized for the CSink. Normally not overridden in CPipe derived classes, as it's normally only a CSink that can provide an efficient alternative. This default implementation simply constructs a CSeg object of the required size. See also: GetSeg() The User callable function. Returns: A writeable segment. Reimplemented from AxPipe::CSink. Definition at line 204 of file CPipe.cpp.

bool AxPipe::CPipe::OutOpen (   )  [protected, virtual]

Overrideable, Open the data stream for processing. Override in user derived classes. Called by the framework as a result of an Open() call here or upstream. Prepare for processing of a new stream, it must support being called again after a Close() call. No data may be processed by the stream without an Open() call. The default implementation for a CPipe returns true, so as to have the framework propagate it downstream. Returns: true if the framework should propagate the Open() request downstream. Reimplemented from AxPipe::CSink. Reimplemented in AxPipe::CSplit, AxPipe::CFilter, AxPipe::CSourceMemFile, AxPipe::Stock::CPipeHMAC_SHA1< iBits >, AxPipe::Stock::CPipeInflate, and AxPipe::Stock::CPipeSHA1. Definition at line 231 of file CPipe.cpp.

bool AxPipe::CPipe::OutSignal (  void *  vId, void *  p )  [protected, virtual]

Overrideable, Receive an out of band signal from upstream. Override in user derived classes to receive a signal sent from upstream. This will be called synchronized with the data stream, so previously sent data will have reached this section, unless some intermediate section buffers. No automatic Flush() request is sent though by the framework. The CPipe default implementation does nothing but returns true to propagate it downstream. Returns: false to stop the signal-propagation, true to continue it. Parameters: vId  A unique value identifying the signal, suggested is ClassId(). p  An opaque pointer value, interpretable by the receiver. See also: CPipe::OutSignal() Reimplemented from AxPipe::CSink. Definition at line 218 of file CPipe.cpp.

longlong AxPipe::CPipe::OutSizeMax (   )  [protected, virtual]

Overrideable, Calculate the maximum size of the CSink. Normally this is not overridden in CPipe derived classes, as it's only the CSink that can do the job. This default implementation passes the call downstream to the final CSink, and then returns the result. Returns: The maximum output size in bytes. -1 if unknown or unlimited. See also: SizeMax() Reimplemented from AxPipe::CSink. Definition at line 194 of file CPipe.cpp. References AxPipe::longlong, m_pSink, and AxPipe::CSink::OutSizeMax().

void AxPipe::CPipe::OutSpecial (  CSeg *  pSeg  )  [protected, virtual]

Overrideable, Process a special segment and send results downstream with Pump(). Segments may be marked as special with a non-zero value based on AxPipe::eSegType types. This are filtered out of the stream by the framework and presented here instead of to Out(). Use this in derived classes to provide in band signalling and for other custom needs. Start numbering special segments with AxPipe::eSegTypeDerived. These segements may be zero-length. See also: AxPipe::eSegType Reimplemented from AxPipe::CSink. Reimplemented in AxPipe::CSplit. Definition at line 252 of file CPipe.cpp. References Pump().

void AxPipe::CPipe::Pump (  CSeg *  pSeg  )

Utility function, call typically from Out(), to send a segment downstream. Parameters: pSeg  The segment to send downstream. Do not refer to after call without call to CSeg::AddRef(). Definition at line 136 of file CPipe.cpp. References m_pSink, AxPipe::CSink::OutPump(), and AxPipe::CSeg::Release(). Referenced by AxPipe::Stock::CPipeSHA1::Out(), AxPipe::Stock::CPipeInflate::Out(), AxPipe::Stock::CPipeHMAC_SHA1< iBits >::Out(), and OutSpecial().

void AxPipe::CPipe::Signal (  void *  vId, void *  p )  [protected, virtual]

Out of band signalling downstream. Callable from user code in derived classes. Called from derived classes processing code, to send an out of band signal with an opaque pointer value as the single argument downstream. This is useful when interpreted data upstream should affect the actions downstream - an example might be parsing an archive and then sending a file name downstream to a AxPipe::CSinkMemFile derived class that supports reception of the name and then opening a file under that name. Parameters: vId  A unique value identifying the signal, suggested is ClassId(). p  An opaque pointer value, interpretable by the receiver. Reimplemented from AxPipe::CSink. Definition at line 178 of file CPipe.cpp. References m_pSink, AxPipe::CSink::OutSignal(), AxPipe::CSink::Signal(), and AxPipe::CNoThread::WaitForIdle().

void AxPipe::CPipe::Sync (   )  [virtual]

Ensure that all threads downstream are idle. Synchronize all work downstream, ensuring that there is no work in progress. Reimplemented from AxPipe::CSink. Reimplemented in AxPipe::CSplit. Definition at line 120 of file CPipe.cpp. References m_pSink, AxPipe::CSink::Sync(), and AxPipe::CNoThread::WaitForIdle(). Referenced by AxPipe::CSplit::Sync().

void AxPipe::CPipe::Work (   )  [protected, virtual]

Process one memory segment, possibly propagating. Called with m_pSeg set to whatever needs to be processed, and will call the appropriate Out function (Out(), OutOpen(), OutClose(), OutFlush() or OutSpecial()) and will also handle Plug() requests by exiting. Guarantees to only call Out() with valid, non-zero-length memory segments. Reimplemented from AxPipe::CSink. Reimplemented in AxPipe::CFilter. Definition at line 65 of file CPipe.cpp. References AxPipe::CSeg::AddRef(), AxPipe::CSink::DoSegWork(), m_pSink, AxPipe::CSink::OutPump(), AxPipe::CSeg::Release(), and AxPipe::CNoThread::WorkExitWait().

---

The documentation for this class was generated from the following files:

• AxPipe.h
• CPipe.cpp

---