IPC Modules Overview
====================

This file provides an introduction into the modules provided by this package.
Working examples can be found in the test/ directory.

nsIPCService
------------
A service that provides high-level access to the other components.
The most important methods are various variants of execPipe, which
allow to execute a file in blocking or non-blocking way, pass
information through stdin to the  executed comamnd, and get back
the output from stdout and stderr (see below for more details).

The input/output is done via the nsIIPCRequest interface provided.


nsIPipeTransport
----------------
Implements nsIRequest.

The nsIPipeTransport interface executes a file in a new process and
communicates with the process using pipes.

OWNERSHIP AND THREADING MODEL for nsPipeTransport:

nsPipeTransport can be created in any thread with an event queue.

nsPipeTransport lives only in the thread that it was created in.

nsPipeTransport creates a helper thread object, nsStdoutPoller and
retains an owning reference to it. nsStdoutPoller also holds a strong
reference to a proxy interface (nsIPipeTransportListener) implemented by
nsPipeTransport, which is released when the polling thread terminates.

The polling thread terminates when it is "interrupted" by
nsPipeTransport or when EOF/error is encountered in reading data from
the process STDOUT.

The "terminate" method should *always* be called to release the process
resources when done.

For asynchronous reading, when nsStdoutPoller terminates of its own
accord, any stream listener is informed by invoking OnStopRequest.
Usually this listener will be the same as the owner of nsPipeTransport.
(If the owner initiates the request shutdown by first calling "cancel",
then the OnStopRequest method is *notinvoked, because it is assumed that
the listener/owner is already aware of the shutdown.)


nsIPipeListener
---------------
Implements a nsIStreamListener sink (thread-safe).


nsIIPCBuffer
------------
Extends nsIPipeListener. nsIIPCBuffer is an interface to a byte buffer.
In order to ensure data integrity, it uses a monitor.


nsIPipeChannel
--------------
Implements a nsIChannel interface. The nsIPipeChannel interface executes
a program in a new process and communicates with the process using pipes.


nsIPipeConsole
--------------
Another extension of nsIPipeListener.
nsIPipeConsole is an interface to a circular text console buffer
(i.e. to capture the results from a pipe).


nsIPipeFilterListener
---------------------
Implements nsIStreamListener; allows to filter the data of the stream.


nsIProcessInfo
--------------

Provides methods for obtaining information about the process.
Currently only getEnv() is available.

