li.cil.tis3d.api.machine

Interface Pipe

All Known Implementing Classes:

PipeImpl

public interface Pipe

A pipe used to move data across Ports between Modules.

Each Casing provides eight ports to each installed module, each pair of modules sharing two pipes, going in both directions. This abstracts data transfer between modules.

Pipes operate in a synchronized manner, ensuring that when two modules start reading and writing on a pipe between them in the same update step, there is no execution-order-dependent behavior: the pipe requires a read and write operation to be started via beginRead() and beginWrite(short), respectively, and will then, after the modules finished their update for the current step switch to a transferring state, so that the modules can finish the operation in the next update.

A transfer is completed by the receiver calling read(), which will reset the pipe and call Module.onWriteComplete(Port) on the writing module.

So in short, a full transfer cycle looks like this:

• Module A starts writing (or reading).
• Module B starts reading (or writing) (in the same or a later update).
• At the end of the update step, the pipe will enter transfer mode, indicated by canTransfer() being true.
• Module B finishes the transfer by calling read().
• Module A has it's Module.onWriteComplete(Port) method called.

Note that at any time during the transfer cycle, one of the two parties may cancel their reading or writing operation by calling cancelRead() or cancelWrite(), respectively. The other part of the transfer will not be explicitly notified of this change, but this can be checked using the isReading() and isWriting() methods.

Method Summary

Modifier and Type	Method and Description
void	beginRead() Begin a reading operation on the pipe.
void	beginWrite(short value) Begin a writing operation on the pipe.
void	cancelRead() Cancel an active read operation.
void	cancelWrite() Cancel an active write operation.
boolean	canTransfer() Whether the pipe can transfer data, i.e.
boolean	isReading() Whether the pipe is currently being read from.
boolean	isWriting() Whether the pipe is currently being written to.
short	read() Finish a read operation by fetching the data that is written by the write operation running at the same time.

Method Detail

beginWrite

void beginWrite(short value)
         throws java.lang.IllegalStateException

Begin a writing operation on the pipe.

Make sure not to call this if the pipe is already being written to, or an exception will be thrown. Use isWriting() to check for this.

Parameters:

value - the value to write to the pipe.

Throws:

java.lang.IllegalStateException - if the pipe is already being written to.

cancelWrite

void cancelWrite()

Cancel an active write operation.

If the pipe is not currently being written to this does nothing.

isWriting

boolean isWriting()

Whether the pipe is currently being written to.

This is true as soon as beginWrite(short) was called and until read() or cancelWrite() was called to finish or cancel the operation.

Returns:

whether the pipe is currently being written to.

beginRead

void beginRead()
        throws java.lang.IllegalStateException

Begin a reading operation on the pipe.

Make sure not to call this if the pipe is already being read from, or an exception will be thrown. Use isReading() to check for this.

Throws:

java.lang.IllegalStateException - if the pipe is already being read from.

cancelRead

void cancelRead()

Cancel an active read operation.

If the pipe is not currently being read from this does nothing.

isReading

boolean isReading()

Whether the pipe is currently being read from.

This is true as soon as beginRead() was called and until read() or cancelRead() was called to finish or cancel the operation.

Returns:

whether the pipe is currently being read from.

canTransfer

boolean canTransfer()

Whether the pipe can transfer data, i.e. read() can be called.

Note that this is not equivalent to isReading() && isWriting(). This is only true in the first update after that has been true and later.

Returns:

whether the pipe can now transfer data.

read

short read()
    throws java.lang.IllegalStateException

Finish a read operation by fetching the data that is written by the write operation running at the same time.

Make sure not to call this if the pipe is not in the correct state, or an exception will be thrown. use canTransfer() to check for this.

This will cause Module.onWriteComplete(Port) to be called on the module currently writing to the pipe, then reset the pipe (i.e. call cancelRead() and cancelWrite()) prior to returning the read value.

Returns:

the value transferred through the pipe.

Throws:

java.lang.IllegalStateException - if the pipe is in an incorrect state.