The twin stream. More...

Files
file	PDTwinStream.h

Typedefs
typedef struct PDTwinStream *	PDTwinStreamRef

Enumerations
enum	PDTwinStreamMethod { PDTwinStreamReadWrite, PDTwinStreamRandomAccess, PDTwinStreamReversed }

Construction
PDTwinStreamRef	PDTwinStreamCreate (FILE fi, FILE fo)

Configuring / querying
void	PDTWinStreamSetMethod (PDTwinStreamRef ts, PDTwinStreamMethod method)

PDScannerRef	PDTwinStreamGetScanner (PDTwinStreamRef ts)

PDScannerRef	PDTwinStreamSetupScannerWithState (PDTwinStreamRef ts, PDStateRef state)

#define	PDTwinStreamGetInputOffset(str) (str->offsi + str->cursor)

#define	PDTwinStreamGetOutputOffset(str) (str->offso)

Reading
void	PDTwinStreamGrowInputBuffer (void ts, PDScannerRef scanner, char buf, PDInteger size, PDInteger req)

void	PDTwinStreamGrowInputBufferReversed (void ts, PDScannerRef scanner, char buf, PDInteger size, PDInteger req)

void	PDTwinStreamDisallowGrowth (void ts, PDScannerRef scanner, char buf, PDInteger size, PDInteger req)

void	PDTwinStreamSeek (PDTwinStreamRef ts, PDSize position)

void	PDTwinStreamAdvance (PDTwinStreamRef ts, PDSize bytes)

PDSize	PDTwinStreamFetchBranch (PDTwinStreamRef ts, PDSize position, PDInteger bytes, char **buf)

void	PDTwinStreamCutBranch (PDTwinStreamRef ts, char *buf)

Committing
void	PDTWinStreamPassthroughContent (PDTwinStreamRef ts)

void	PDTwinStreamDiscardContent (PDTwinStreamRef ts)

void	PDTwinStreamInsertContent (PDTwinStreamRef ts, PDSize bytes, const char *content)

void	PDTwinStreamPrune (PDTwinStreamRef ts, PDOffset mark)

PDScannerRef	PDTwinStreamCreateScanner (PDTwinStreamRef ts, PDStateRef state)

Detailed Description

The twin stream.

The twin stream is similar to how a *NIX pipe works, except it provides functionality for jumping back and forth in the input stream while simultaneously streaming data through the scanner, parser, and into the output stream.

Generally, this is done in the following steps, iterated over and over until the input ends:

Request to grow some buffer comes in.
Pull data from input stream onto heap and drop buffer inside heap.
Request to discard/pass through content comes in from parser, at which point the master scanner position is adjusted.

Beyond this, there are also requests to insert content.

Macro Definition Documentation

#define PDTwinStreamGetInputOffset ( str ) (str->offsi + str->cursor)

Get the absolute input offset for the given stream.

Parameters

str Stream.

#define PDTwinStreamGetOutputOffset ( str ) (str->offso)

Get the absolute output offset for the given stream.

Parameters

str Stream.

Typedef Documentation

typedef struct PDTwinStream* PDTwinStreamRef

A double-edged stream.

Enumeration Type Documentation

enum PDTwinStreamMethod

The twin stream has three methods available for reading data: read/write, random access, and reversed.

Read/write is the default method, and is the only method allowed for writing to the output stream.
Random access turns the stream temporarily into a regular file reader, permitting random access to the input file. This mode is used when collecting XREF tables on parser initialization.
Reverse turns the stream inside out, in the sense that the heap is filled from the bottom, and buffer fills begin at the end and iterate back toward the beginning.

Enumerator
PDTwinStreamReadWrite	reads and writes from start to end of input into output, skipping/replacing/inserting as appropriate
PDTwinStreamRandomAccess	random access, jumping to positions in the input, not writing anything to output
PDTwinStreamReversed	reads from the end of the input file, filling the heap from the end up towards the beginning

Function Documentation

void PDTwinStreamAdvance	(	PDTwinStreamRef	ts,
		PDSize	bytes
	)

Iterate forward `bytes' bytes in input file

Warning: Behavior undefined unless PDTwinStreamRandomAccess has been set.

Parameters

ts	The stream.
bytes	Number of bytes to advance in input stream.

PDTwinStreamRef PDTwinStreamCreate	(	FILE *	fi,
		FILE *	fo
	)

Create a new stream with the given file handlers.

Parameters

fi	Input file handler.
fo	Output file handler.

PDScannerRef PDTwinStreamCreateScanner	(	PDTwinStreamRef	ts,
		PDStateRef	state
	)

Create a new scanner for use in this stream.

Parameters

ts	The stream
state	Root state

Returns: The new scanner, with is context set up to grow from this stream

void PDTwinStreamCutBranch	(	PDTwinStreamRef	ts,
		char *	buf
	)

Deallocate (if necessary) a fetched branch buffer.

Parameters

ts	The stream.
buf	The buffer.

void PDTwinStreamDisallowGrowth	(	void *	ts,
		PDScannerRef	scanner,
		char **	buf,
		PDInteger *	size,
		PDInteger	req
	)

Do not grow buffer. A call to this method will flag the outgrown flag.

Parameters

ts	PDTwinStreamRef instance
scanner	The scanner making the request.
buf	Pointer to buffer that should be grown.
size	Pointer to size variable that contains current size, and should be updated with new size after growth.
req	The requested amount of data. If 0, an optimal amount in terms of performance is selected.

void PDTwinStreamDiscardContent ( PDTwinStreamRef ts )

Discard content by not writing it to output.

Parameters

ts	The stream.

PDSize PDTwinStreamFetchBranch	(	PDTwinStreamRef	ts,
		PDSize	position,
		PDInteger	bytes,
		char **	buf
	)

Temporarily jump to and read given amount from given offset in input, then immediately jump back to original position.

Note: Uses existing heap if position + size is within bounds. Extends heap if appropriate, otherwise seeks to and reads the content into buf directly.; buf may become invalidated as soon as any of the other functions are used, but should be discarded using PDTwinStreamCutBranch() when no longer needed.

Parameters

ts	The stream.
position	The absolute position to seek to.
bytes	Number of bytes to read
buf	Pointer to string that should be updated. The string must not be freed. Instead, PDTwinStreamCutBranch() should be used, or nothing done at all.

Returns: The actual amount read (which may be lower, e.g. if EOF is hit).

PDScannerRef PDTwinStreamGetScanner ( PDTwinStreamRef ts )

Get twin stream scanner.

This is NULL until set up with a state.

Parameters

ts	The stream.

void PDTwinStreamGrowInputBuffer	(	void *	ts,
		PDScannerRef	scanner,
		char **	buf,
		PDInteger *	size,
		PDInteger	req
	)

Grow buffer (reallocating if necessary) to where it holds the requested amount.

Fitted for PDScannerBufFunc

Initial buffers are obtained by passing NULL as buffer with 0 as size

Warning: Passing a NULL buffer with non-zero size or vice versa is undefined; Behavior is undefined if PDTwinStreamReversed has been set

Parameters

ts	PDTwinStreamRef instance
scanner	The scanner making the request.
buf	Pointer to buffer that should be grown.
size	Pointer to size variable that contains current size, and should be updated with new size after growth.
req	The requested amount of data. If 0, an optimal amount in terms of performance is selected.

void PDTwinStreamGrowInputBufferReversed	(	void *	ts,
		PDScannerRef	scanner,
		char **	buf,
		PDInteger *	size,
		PDInteger	req
	)

Grow buffer backwards, i.e. by prepending the buffer with previous content.

Warning: Behavior is undefined unless PDTwinStreamReversed has been set

Parameters

ts	PDTwinStreamRef instance
scanner	The scanner making the request.
buf	Pointer to buffer that should be grown.
size	Pointer to size variable that contains current size, and should be updated with new size after growth.
req	The requested amount of data. If 0, an optimal amount in terms of performance is selected.

void PDTwinStreamInsertContent	(	PDTwinStreamRef	ts,
		PDSize	bytes,
		const char *	content
	)

Insert new content into output.

Parameters

ts	The stream.
bytes	Number of bytes to write.
content	The content to write.

void PDTWinStreamPassthroughContent ( PDTwinStreamRef ts )

Pass through content based on the master scanner's position in the stream.

Parameters

ts	The stream.

void PDTwinStreamPrune	(	PDTwinStreamRef	ts,
		PDOffset	mark
	)

Prune the stream.

This is basically only used when updating objects, to preserve prefix content in scanner iteration.

Parameters

ts	The stream.
mark	Comparison mark.

void PDTwinStreamSeek	(	PDTwinStreamRef	ts,
		PDSize	position
	)

Jump to byte position in input file

Warning: behavior undefined unless PDTwinStreamRandomAccess has been set

Parameters

ts	The stream.
position	The absolute position to seek to.

void PDTWinStreamSetMethod	(	PDTwinStreamRef	ts,
		PDTwinStreamMethod	method
	)

Set the stream method for the given stream.

Parameters

ts	The stream.
method	The PDTwinStreamMethod.

See also: PDTwinStreamMethod

PDScannerRef PDTwinStreamSetupScannerWithState	(	PDTwinStreamRef	ts,
		PDStateRef	state
	)

Set up twin stream scanner with given state.

It can be set multiple times. Previous instances are destroyed

Parameters

ts	The stream.
state	The state.

Files

Typedefs

Enumerations

Construction

Configuring / querying

Reading

Committing

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation