NAME

filter − data processing interface

SYNOPSIS

include "filter.m";
filter = load Filter FilterModulePath;
 

Rq: adt {
pick {
Start =>
pid: int;
Fill or Result =>
buf: array of byte;
reply: chan of int;
Finished =>
buf: array of byte;
Info =>
msg: string;
Error =>
e: string;
}
};
 init: fn();
start: fn(param: string): chan of ref Rq;

DESCRIPTION

­Filter defines a general module interface for byte-stream processing.  This manual page documents how to use the interface, and by implication how a ­Filter module should behave.  For details of the filter modules that exist, see filters(2).

­Init must be called when a filter module has been loaded, to initialise any internal data structures.  ­Start sets the filter going; ­param can be used to pass any filter-specific information to the processor.  ­Start spawns a new thread to do the processing; it returns a channel that is used to receive requests from the filter. The first message sent is always Rq.Start; ­pid is the process id of the new process spawned.  Other messages are:

­Rq.Fill A request by the filter to fill ­buf with data.  The number of bytes that have actually been placed in the buffer should be sent on reply. If −1 is sent, the filter will terminate. If the value is 0, the filter will terminate once it has processed all its input.

­Rq.Result
­Buf contains data from the filter.  Receipt of the the data must be acknowledged by sending a value on reply. If the value is −1, the filter will terminate.

­Rq.Finished
The filter has finished processing. ­Buf contains the data that remains unconsumed by the filter, if any. The filter terminates after sending this message. 

­Rq.Info This message is used to communicate a string of arbitrary information from the filter during the course of its processing. 

­Rq.Error The filter has encountered an error when processing.  ­E is a string describing the error. The filter terminates after sending this message. 

SOURCE

­/module/filter.m

SEE ALSO

filters(2), gzip(1)

Plan 9  —  June 29, 2000