|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object com.lts.ipc.fifo.FIFO
public class FIFO
A one-way interprocess communications channel.
create()
method before the named pipe can be
used. This is in addition to whether that process will be exclusively reading from or
writing to the pipe.
On Linux, a named pipe (FIFO) will persist after the process that created it terminates, allowing subsequent clients to use it without taking on a client or role.
Unfortunately, using this information will introduce a platform dependency in the system.
byte[] buffer;
String name;
// create an instance for buffer and fill it with data
// set name to a valid file name
...
NamedPipe pipe = new NamedPipe(name);
pipe.create();
pipe.openWriter();
pipe.write(buffer);
byte[] buffer;
String name;
// create an instance for buffer
// set name to the same name as the writer is using
...
NamedPipe pipe = new NamedPipe(name);
pipe.openReader();
int count = pipe.read(buffer);
// process the data received
...
This class provides a named pipe IPC primitive. These are sometimes referred to as FIFOs or message queues.
In this context a named pipe provides a one-way, synchronous communications channel between two processes. Note that this class only allows one-way communications even if the underlying mechanism the operating system supports is two-way.
The class uses file naming as explained in the package description. In the case of this class, the file name will refer to an operating system file. On Linux, this will be the name of the FIFO that is a file in the file system that implements the pipe. On windows, this will be a file that contains the actual name of the pipe.
Before using an instance of the class, the openReader()
or
openWriter()
method should be used to establish the role it will be taking
when communicating. Attempting to use an instance without properly initializing may
result in unpredictable behavior.
Once the role has been established the read(byte[])
,
read(byte[], int, int)
, write(byte[])
and
write(byte[], int, int)
methods, as appropriate, can be used to send or
receive information.
This class uses virtual and actual files to implement the underlying primitive. On platforms such as Linux, the virtual and actual file names are the same and both refer to a special file on the system that represents the communications channel.
In the case of Windows, named pipes must use a special file name of the form: \\.\pipe\<name>
. Such file names cannot be used on Linux.
In order to provide a reasonably platform independent solution, the Windows implementation of named pipes uses two file names for the pipe: a virtual name name and an actual name.
The virtual name is basically any valid file name on the system. The file identified in the virtual name corresponds to an actual file in the system, which contains the actual name of the named pipe.
The actual name is then used to identify the named pipe to Windows.
Nested Class Summary | |
---|---|
static class |
FIFO.BlockingMode
|
Field Summary | |
---|---|
static int |
DEFAULT_BUFFER_SIZE
|
Constructor Summary | |
---|---|
FIFO(java.lang.String virtualName)
Create a named pipe with the specified virtual name. |
|
FIFO(java.lang.String virtualName,
int timeoutMsec)
|
Method Summary | |
---|---|
void |
create()
|
protected java.lang.String |
getActualName()
|
FIFO.BlockingMode |
getBlockingMode()
|
protected FIFOImpl.PipeDirection |
getDirection()
|
protected FIFOImpl |
getImpl()
|
java.io.InputStream |
getInputStream()
|
java.io.InputStream |
getInputStream(int timeoutMsec)
|
java.io.OutputStream |
getOutputStream()
|
int |
getTimeoutMsec()
|
java.lang.String |
getVirtualName()
|
protected void |
initialize(java.lang.String virtualName)
|
void |
open(FIFOImpl.PipeDirection direction)
Open the named pipe, taking on the role of reader or writer. |
void |
openReader()
Connect to the named pipe, taking on the role of reader. |
void |
openWriter()
Connect to the named pipe, taking on the role of writer. |
int |
read(byte[] buffer)
Read from the named pipe, blocking until data becomes available. |
int |
read(byte[] buffer,
int offset,
int length)
Read some data from the named pipe, blocking if the data is not available. |
protected java.lang.String |
readActualName(java.lang.String virtualName)
|
void |
selectForWriting(int timeoutMsec)
|
void |
setBlockingMode(FIFO.BlockingMode blockingMode)
|
protected void |
setDirection(FIFOImpl.PipeDirection direction)
|
protected void |
setImpl(FIFOImpl impl)
|
void |
setTimeoutMsec(int timeout)
|
int |
write(byte[] buffer)
Write some data to the named pipe. |
int |
write(byte[] buffer,
int offset,
int length)
Write some data to the named pipe. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final int DEFAULT_BUFFER_SIZE
Constructor Detail |
---|
public FIFO(java.lang.String virtualName)
virtualName
- The file to be used for the named pipe. See the class description for
details about how and why the virtual file name is
used. public FIFO(java.lang.String virtualName, int timeoutMsec)
Method Detail |
---|
public FIFO.BlockingMode getBlockingMode()
public void setBlockingMode(FIFO.BlockingMode blockingMode)
public int getTimeoutMsec()
public void setTimeoutMsec(int timeout)
protected FIFOImpl getImpl()
protected void setImpl(FIFOImpl impl)
protected void initialize(java.lang.String virtualName)
public void create() throws IPCException
IPCException
protected java.lang.String readActualName(java.lang.String virtualName) throws IPCException
IPCException
public void open(FIFOImpl.PipeDirection direction) throws IPCException
On Linux, users of named pipes need to either read or write to a named pipe, they should not do both. Therefore this method establishes how the client is going to use the pipe and then connects to it.
direction
- The role the client wants to take on: reader or writer.
IPCException
- If a problem is encountered while trying to connect to the pipe.public void openWriter() throws IPCException
This method is equivalent to calling #open(PipeDirection)
with an argument
of FIFOImpl.PipeDirection.Writer
.
IPCException
- If a problem is encountered while trying to connect to the pipe.#open(PipeDirection)
public void openReader() throws IPCException
This method is equivalent to calling #open(PipeDirection)
with an argument
of FIFOImpl.PipeDirection.Reader
.
IPCException
- If a problem is encountered while trying to connect to the pipe.#open(PipeDirection)
protected FIFOImpl.PipeDirection getDirection()
protected void setDirection(FIFOImpl.PipeDirection direction)
protected java.lang.String getActualName()
public int read(byte[] buffer) throws IPCException
This method is equivalent to calling read(buffer, 0, buff.length). See that class for additional details.
buffer
- The buffer where the data read from the pipe should be placed.
IPCException
- If a problem is encountered while reading from the named pipe.read(byte[], int, int)
public int read(byte[] buffer, int offset, int length) throws IPCException
This method will block if data is not available when it is called. The method may read less than the specified amount of data.
It is an error on some platforms to read from a pipe that has been opened for writing.
buffer
- The buffer where the data read should be placed.offset
- Where the data should start in the buffer.length
- The size of the buffer, in bytes.
IPCException
- If a problem is encountered while trying to read from the pipe.public int write(byte[] buffer) throws IPCException
This method is equivalent to calling write(buffer, 0, buffer.length). Please see that method for additional details.
buffer
- The buffer that contains the data.
IPCException
- If a problem is encountered while writing the data.public int write(byte[] buffer, int offset, int length) throws IPCException
This method writes data to the named pipe and will block if the pipe is currently full.
It is an error to write to a named pipe that the client opened as a reader.
The method may perform a partial write, in which case only some of the data in the buffer was actually written. In that case, the return value will be less than the length parameter.
buffer
- The buffer that contains the data to write.offset
- Where in the buffer that the data starts.length
- The number of bytes of data to write.
IPCException
- If a problem is encountered while trying to write the data.public java.io.InputStream getInputStream(int timeoutMsec) throws java.io.IOException
java.io.IOException
public java.io.InputStream getInputStream() throws java.io.IOException
java.io.IOException
public java.io.OutputStream getOutputStream() throws java.io.IOException
java.io.IOException
public java.lang.String getVirtualName()
public void selectForWriting(int timeoutMsec)
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |