AxPipe::CFilter Class Reference

A buffering filter enabling a pull programming-model. More...

#include <AxPipe.h>

Inheritance diagram for AxPipe::CFilter:

[legend]Collaboration diagram for AxPipe::CFilter:

[legend]List of all members.

Public Member Functions
	CFilter ()
	Initialize member variables.
Protected Member Functions
bool	OutOpen ()
	Prepare for processing.
bool	OutClose ()
	Send a NULL segment close signal to InFilter() and Read().
bool	OutFlush ()
	Send flush-request as a zero-length segment to Read().
void	Work ()
	Send the m_pSeg segment to the Filter.
CSeg *	Read ()
	Get a segment, call from InFilter().
virtual void	InFilter ()=0
	The main override in a CFilter derived class.
Protected Attributes
CCoContext	m_ctxWork
	The Work() co-routine context, actually the caller current.
Private Member Functions
void	CoStartFilter (void *pvThis)
	The start in-class of the filter co-routine context. We get here when we have the first data segment ready for the InFilter() and we're opened by the previous.
void	Out (CSeg *pSeg)
	Overriden Out() to handle switching to Filter co-routine context.
Static Private Member Functions
void	CoFilter (void *pvThis)
	Helper static member function to send as StartProc to the CCoContext m_ctxFilter.
Private Attributes
bool	m_fFirstWork
	true until first call of Work()
CCoContext	m_ctxFilter
	The InFilter() co-routine context, a newly created context.

---

Detailed Description

A buffering filter enabling a pull programming-model.

There are some differences in the handling of pull model CFilter based classes. Flush() has no effect in the pull-model filter.

Instead of overriding Out(), you should override InFilter(). There you use Open(), Read(), Pump() and Close() to perform opening, reading writing and closing respectively.

When run in the threading version, InFilter() will execute in a separate thread (as will downstream processing, until a new threaded section is encountered).

All CFilter derived classes use a co-routine context to handle the reversal from push to pull model. Essentially we initialize two co-routine contexts, one for the caller Work(), which calls Out(), and one for InFilter() and Read(). Thus, when a segment arrives (is pushed), we switch to the InFilter context which will the use Read() to pick up the waiting section. When Read() is then called to get the next segment, it switches back to the Work co-routine, which will wait for the next segment to arrive before switching back etc etc.

Definition at line 459 of file AxPipe.h.

---

Member Function Documentation

void AxPipe::CFilter::CoFilter (  void *  pvThis  )  [static, private]

Helper static member function to send as StartProc to the CCoContext m_ctxFilter. It's only function is to get us 'back into the class', by calling CoStartFilter(). Parameters: pvThis  A pointer to 'this' CFilter. Definition at line 41 of file CFilter.cpp. References _T, and ASSCHK.

void AxPipe::CFilter::CoStartFilter (  void *  pvThis  )  [private]

The start in-class of the filter co-routine context. We get here when we have the first data segment ready for the InFilter() and we're opened by the previous. Parameters: pvThis  A pointer to 'this' CFilter (not really necessary). Definition at line 135 of file CFilter.cpp. References _T, AxPipe::CCoContext::Go(), InFilter(), AxPipe::CSeg::Len(), and m_ctxWork.

virtual void AxPipe::CFilter::InFilter (   )  [protected, pure virtual]

The main override in a CFilter derived class. Override and perform all processing function here. Use Read() to get data, checking for NULL which indicates that this (sub)stream is empty, and zero-length segments which indicate a flush request. Always ensure that Open() get's called before getting any data with Read(), and that Close() get's called after the last data is read. Also be prepared to be called multiple times. Implemented in CFilterNop. Referenced by CoStartFilter().

void AxPipe::CFilter::Out (  CSeg *  pSeg  )  [private, virtual]

Overriden Out() to handle switching to Filter co-routine context. A CFilter derived Out() may be called with zero-length and NULL pSeg from OutClose() and OutFlush(), as this is how those conditions are signalled to the InFilter() via Read(). Parameters: pSeg  The segment to send to the filter. Implements AxPipe::CPipe. Definition at line 64 of file CFilter.cpp. References AxPipe::ERROR_CODE_NOTOPEN, AxPipe::CCoContext::Go(), m_ctxFilter, and AxPipe::CError::SetError(). Referenced by OutClose(), and OutFlush().

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

Send a NULL segment close signal to InFilter() and Read(). If overriden in derived classes, CFilter::OutClose() must also be called, to ensure signalling to InFilter() / Read() . Normally this will not be overridden for CFilter derived classes. Returns: true to cause propagation of Close() - the default here is false. Reimplemented from AxPipe::CPipe. Definition at line 107 of file CFilter.cpp. References Out().

bool AxPipe::CFilter::OutFlush (   )  [protected, virtual]

Send flush-request as a zero-length segment to Read(). Returns: true to cause propagation of Flus() - the default here is true. Reimplemented from AxPipe::CSink. Definition at line 116 of file CFilter.cpp. References Out().

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

Prepare for processing. Filters by default do nothing on Open() request, this is called by Work() in the worker thread upon reception of the open in band signal. If overriden in derived classes, CFilter::OutOpen() must also be called, to ensure proper co-routine context initialization. Normally this will not be overridden for CFilter derived classes. Returns: true to cause propagation of Open() - the default here is false. Reimplemented from AxPipe::CPipe. Definition at line 88 of file CFilter.cpp. References _T, AxPipe::CCoContext::Go(), m_ctxWork, and m_fFirstWork.

CSeg * AxPipe::CFilter::Read (   )  [protected]

Get a segment, call from InFilter(). Get a valid, zero-length or NULL segment for data, flush and close respectively. Returns: A memory segment, or zero-length or NULL (not an error). Reimplemented in AxPipe::CFilterByte. Definition at line 158 of file CFilter.cpp. References AxPipe::CCoContext::Go(), and m_ctxWork.

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

Send the m_pSeg segment to the Filter. This override of the default adds the stopping of the filter context upon reception of a plug signal. Reimplemented from AxPipe::CPipe. Definition at line 126 of file CFilter.cpp.

---

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

• AxPipe.h
• CFilter.cpp

---