DataPipe

Kok Chen, W7AY
[ w7ay (at) arrl.net ]
November 4, 2008


Overview


DataPipe is a Cocoa class that acts as a data pipeline. NSPipe in the Cocoa AppKIt is not completely thread safe. NSPipe uses, for example, autoreleased objects that could released or drained at inopportune times. DataPipe attempts to create a simple and easy to use, thread-safe data pipeline between separate threads.

Unlike NSPipe, DataPipe does not use NSFileHandle. You write directly to DataPipe and read directly from DataPipe objects. As such, DataPipe is probably not suitable for data pipelines that can grow indefinitely before it is read. The "capacity" of the pipe is specified when you initialize DataPipe, and the write port will block (and time out) if the capacity is reached and no one is reading the data.


Download


The DataPipe sources can be downloaded from here.


Tasks


Creating instances

End of File condition

Data reads and writes



Instance Methods


eof

Returns the EOF condition of the pipe. EOF is set using setEOF. Once EOF is set, DataPipe reads will return -1.

- (Boolean)eof

Return Value

The current state of the EOF flag.



init

This is the same as initWithCapacity:512.

- (id)init

Return Value

An initialized DataPipe object.



initWithCapacity

Initializes and returns a newly allocated DataPipe object with the specified capacity.

- (id)initWithCapacity:(int)capacity

Parameters

capacity
The capacity of the pipe in number of bytes. When this capacity is reached, a write to DataPipe will block (or time out) until the pipe data is extracted by some read messages.

Return Value

An initialized DataPipe object.




readData

Reads a fixed number of bytes from the pipe.

- (int)readData(void*)buffer length:(int)bytes

Parameters

buffer
A buffer to read the data into. Must have enough memory allocated to store the number of bytes requested.

bytes
The number of bytes requested.

Discussion

The readData operation blocks until the number of requested bytes has arrived in the pipeline.

Return Value

The number of bytes read.




readAvailableData

Reads the available data from the pipe, up to a maximum number.

- (int)readAvailableData(void*)buffer max:(int)maxBytes

Parameters

buffer
A buffer to read the data into. Must have enough memory allocated to store maxBytes requested.

maxBytes
The maximum number of bytes to read.

Return Value

The number of bytes read.

Discussion

readAvailableData immediately returns 0 there is no data in the pipeline.




setEOF

Sets the EOF condition of the pipe. The EOF condition can be read back with the eof message. Once EOF is set, DataPipe reads will return -1.

- (void)setEOF




write

Write a number of bytes into the pipe.

- (int)write:(void*)buffer length:(int)bytes

Parameters

buffer
A buffer to copy into the pipe.

bytes
The number of bytes to be written.


Return Value

The number of bytes actually written.

Discussion

If the capacity of the pipe is reached, the write operation will wait 1 second for the pipeline to be drained by a read operation. When the 1 second has been reached, the write operation will return with a byte count of the number of bytes it has succeeded in writing.