Utility and Overrideable Functions

Use the basic components and then derive custom classes to perform whatever data transformation, condensation or generation needed.

Utility functions

The framework provides a number of functions that are intended to be called by code in user derived classes. You should normally not override these implementions, but just call them when appropriate. See the section on Overrides below. The most important are:

• AxPipe::CPipe::Open() A data stream must be opened before processing. It may be opened and closed any number of times from construction to destruction via AxPipe::CSource::Plug().
• AxPipe::CPipe::Flush() Send a voluntary request to flush buffered data downstream.
• AxPipe::CPipe::Close() Ends the current processing of data, and prepares for a Open() call again.
• AxPipe::CPipe::Signal() Send an out of band signal to downstream objects.
• AxPipe::CPipe::Pump() Send data downstream after processing.
• AxPipe::CFilter::Read() Get data for processing in pull model AxPipe::CFilter based derived classes.
• AxPipe::CError::SetError() Report an error, also causing processing to end and the CSource to simulate and end of stream situation to end processing.

Overrideable functions

Most utility functions above have a corresponding overrideable virtual implementation. The utility function calls really just wrap the actual implementations and handle propagation downstream or upstream in the case of errors.

Most overrides have the same name as the utility function, but prefixed with Out, such as:

• AxPipe::CPipe::Out() The actual processing in a push model AxPipe::CPipe derived class.
• AxPipe::CPipe::OutOpen() Actually do what is required to open the stream.
• AxPipe::CPipe::OutFlush() Actually do what is required to flush buffered data.
• AxPipe::CPipe::OutClose() Close the stream, prepare for new AxPipe::CPipe::OutOpen().
• AxPipe::CPipe::OutSignal() Receive a signal, and check if it's relevant to this object.
• AxPipe::CFilter::InFilter() The actual processing in a AxPipe::CFilter derived class.

In most cases you should call the base class implementation as part of the derived implementation.

Non-default Constructors

Due to the way the framework is to be used, you should not provide anything but elaborations on the default constructor in your derived classes. When you neeed further initialization, please use and call a separate member function like the following:

    public:
        CPipeMyDerivation *Init(...) {
            ...
            return this;
        }

Threading

To enable threading any CSink or CSource-derived class, use the template CThread as a wrapper, for example:

    pipe->Append(new CThread<CPipeReplace>);    // Run in a separate thread

Note that the threaded class and all that follow it down the pipe are run in the same thread, unless a new threaded class is appended to the chain.

Naming Conventions

A convention is to name derived classes with the prefix CPipe, CSplit, CJoin, CSink or CSource before the rest of the name. CPipe is used for all kinds of intermediate transformations. If it's a threading version, and you define the class explicitly, name it CTPipe, CTSplit etc.

AxPipe::CSeg pointers are usually named pSeg or variants thereof.

See also:

Introduction, Installation, A First Example, A Second Examle, Definitions of Terms, Stock Transformations, Utilities and Overrides

---