mozilla
Your Search Results

    nsIPipe

    This interface represents an in-process buffer that can be read using nsIInputStream and written using nsIOutputStream.
    Inherits from: nsISupports Last changed in Gecko 1.6

    Method overview

    void init(in boolean nonBlockingInput, in boolean nonBlockingOutput, in unsigned long segmentSize, in unsigned long segmentCount, in nsIMemory segmentAllocator);

    Attributes

    Attribute Type Description
    inputStream nsIAsyncInputStream The pipe's input end, which also implements nsISearchableInputStream. Read only.
    outputStream nsIAsyncOutputStream The pipe's output end. Read only.

    Methods

    init()

    initialize this pipe.

    void init(
      in boolean nonBlockingInput,
      in boolean nonBlockingOutput,
      in unsigned long segmentSize,
      in unsigned long segmentCount,
      in nsIMemory segmentAllocator
    );
    
    Parameters
    nonBlockingInput
    true specifies non-blocking input stream behavior.
    nonBlockingOutput
    true specifies non-blocking output stream behavior.
    segmentSize
    Specifies the segment size in bytes (pass 0 to use default value)
    segmentCount
    Specifies the max number of segments (pass 0 to use default value). Passing PR_UINT32_MAX here causes the pipe to have "infinite" space. This mode can be useful in some cases, but should always be used with caution. The default value for this parameter is a finite value.
    segmentAllocator
    Pass reference to nsIMemory to have all pipe allocations use this allocator (pass null to use the default allocator)

    Remarks

    The reader and writer of a pipe do not have to be on the same thread. As a result, the pipe is an ideal mechanism to bridge data exchange between two threads. For example, a worker thread might write data to a pipe from which the main thread will read.

    Each end of the pipe can be either blocking or non-blocking. Recall that a non-blocking stream will return NS_BASE_STREAM_WOULD_BLOCK if it cannot be read or written to without blocking the calling thread. For example, if you try to read from an empty pipe that has not yet been closed, then if that pipe's input end is non-blocking, then the read call will fail immediately with NS_BASE_STREAM_WOULD_BLOCK as the error condition. However, if that pipe's input end is blocking, then the read call will not return until the pipe has data or until the pipe is closed. This example presumes that the pipe is being filled asynchronously on some background thread.

    The pipe supports nsIAsyncInputStream and nsIAsyncOutputStream, which give the user of a non-blocking pipe the ability to wait for the pipe to become ready again. For example, in the case of an empty non-blocking pipe, the user can call nsIAsyncInputStream.AsyncWait() on the input end of the pipe to be notified when the pipe has data to read (or when the pipe becomes closed).

    NS_NewPipe2() and NS_NewPipe() provide convenient pipe constructors for C++. In most cases nsIPipe is not actually used. It is usually enough to just get references to the pipe's input and output end. In which case, the pipe is automatically closed when the respective pipe ends are released.

    Document Tags and Contributors

    Contributors to this page: Sheppy
    Last updated by: Sheppy,