a0NewPipe()

Creates a new pipe.

Syntax

`a0tError`	`a0NewPipe(`
		`a0tPipe`	`*pipe,`
		`a0tPort`	`*port,`
		`int`	`othernode,`
		`int`	`tag,`
		`size_t`	`bufsize,`
		`int`	`protocol,`
		`int`	`priority );`

Arguments

Name	rd/wr	Description
pipe	write	Pipe created.
port	read	Port to listen or talk.
othernode	read	Node to connect with.
tag	read	Tag to use in connection.
bufsize	read	Size of the communication buffer.
protocol	read	Protocol of the pipe.
priority	read	Priority of the pipe.

Description

This function creates a pipe descriptor to be used in subsequent a0FPut() and a0FGet() functions calls. It must be called in a pair of nodes, creating a connected, point-to-point, buffered communication pipe between these two nodes. One node must specify that the pipe has A0InputPipe in the protocol, the other must specify A0OutputPipe, defining the direction of the communication. The writer node must pass the reader port, the reader node as othernode and a tag. The reader node must specify its port, the writer node as othernode and the same tag.

The buffer size used can be specified in bufsize. The default size is A0DefaultPipeSize. A new thread is created to listen or talk in the pipe, with a priority stated in priority.

protocol is an integer bitmask that contains A0OutputPipe or A0InputPipe, bitwise-ored with one of the following:

A0AsyncPipe: put/get requests are stored in a queue. There is a secondary thread which packes/unpackes the requests into/from a buffer. If buffer is full/empty, the secondary thread blocks to send/receive the buffer. If data doesn't fit in the buffer, the secondary thread cuts it and packs/unpacks a part of it. It allows data to be put/get with different formats on each side.
A0SyncPipe: Put/get calls pack/unpack data into/from a buffer. If buffer is full/empty, the thread blocks to send/receive the buffer. If data doesn't fit in the buffer, the thread cuts it and packs/unpacks a part of it. It allows data to be put/get with different formats on each side, but no non-blocking put/get is allowed.

In some cases, large data must be transported through a pipe. If the buffer size is considerably small, a large amount of messages will be used to send it. When the communication is done in only one way, from one single node to another, flow control may be necessary to avoid bufeer overflow. To enable flow control in a pipe, use A0FlowPipe bitwise-ored to the chosen protocol.

To send the contents of the buffer in an A0OutputPipe, even when it is not full, there is a function called a0Flush(). After stop using a pipe, it must be disposed with a0DisposePipe(), which also causes a flush. a0Terminate() does not flush any pipes.

Return Values

If an error condition occurs, it returns the error code, otherwise it returns A0ErrOk. Possible values are as follows:

Error Code	Description
`A0Err...`	Some error occurred.
`A0ErrOk`	Successful completion.

a0NewPipe()

Syntax

Arguments

Description

Return Values

See Also