Like CmdSpec in System.Process, but also has an instance for Show.

When dealing with a Handle, errors can occur when reading from, writing to, or closing the handle.

The two kinds of outbound handles.

Describes a handle. From the perspective of the subprocess; for example, Input means that this handle is connected to the process's standard input.

Describes all IO exceptions. The Oopsie contains the IOException itself, along with the CmdSpec that was running when the exception occurred.

The exceptions that are caught and placed into an Oopsie may arise from reading data from or writing data to a Handle. In these errors, the associated Producer or Consumer will terminate (which may trigger various cleanup actions in the MonadSafe computation) but the exception itself is not re-thrown; rather, it is passed to the handler. Similarly, an exception may occur while closing a handle; these exceptions are caught, not rethrown, and are passed to the handler. If an exception arises when terminating a process (I'm not sure this is possible) then it is also caught, not rethrown, and passed to the handler.

If an exception arises when creating a process--such as a command not being found--the exception is not caught, handled, or passed to the handler. In addition, no exceptions are caught if they originated during a waitForProcess. (I can't conceive of how any synchronous exceptions could arise from waitForProcess, but if they do, Cliff does not handle them.) Also, an Oopsie is created only for an IOException; no other exceptions of any kind are caught or handled. However, exceptions of any kind will still trigger appropriate cleanup actions in the MonadSafe computation.

Formats an Oopsie for display.

The default handler when receiving an Oopsie; simply uses renderOopsie to format it nicely and put it on standard error.

Side effects: gets the program name from the environment, and prints the Oopsie to standard error.

How will the subprocess get its information for this stream? A NonPipe is used for streams that will not be assigned to a Proxy but, instead, will be inherited from the parent or directed from an existing Handle.

Like CreateProcess in System.Process, this gives the necessary information to create a subprocess. All but one of these fields is also present in CreateProcess, and they all have the same meaning; the only field that is different is the handler field.

Do not show or do anything with exceptions; useful to use as a handler.

Side effects: None.

Create a CreateProcess record with default settings. The default settings are:

• a raw command (as opposed to a shell command) is created
• the current working directory is not changed from the parent process
• the environment is not changed from the parent process
• the parent's file descriptors (other than standard input, standard output, and standard error) are inherited
• no new process group is created
• delegate_ctlc, detach_console, create_new_console, and new_session are all False
• child_group and child_user are both Nothing
• handler is defaultHandler

Guarantees single-thread access

All MVar idioms thanks to Neil Mitchell: http://neilmitchell.blogspot.com/2012/06/flavours-of-mvar_04.html

Operates on mutable variables in thread-safe way.

Starts with no value, is written to once, and is read one or more times.

Takes an action and returns a new action. If the action is never called the argument action will never be executed, but if it is called more than once, it will only be executed once.

Side effects: creates a Var. Returns an IO action that modifies the contents of that Var.

Creates a new mailbox. Returns an action to send to the mailbox; this action will return False if the mailbox is sealed, or True if the message was successfully placed in the mailbox. Also returns an action to retrieve from the mailbox, which returns Nothing if the mailbox is sealed, or Just if there is a value to be retrieved. Also returns an action to seal the mailbox.

Data that is computed once, after the process has been created. After computation, this data does not change.

Is this process still running?

Side effects: examines the process handle to see if it has yet returned a value. Does not block; should return immediately.

Allows you to terminate the process, as well as to obtain some information about the process.

Tells you the CreateProcess that was originally used to create the process associated with this ProcessHandle.

Add a finalizer to the ProcessHandle. When the finalizers are run, all exceptions are ignored, except asynchronous exceptions, which are masked.

Terminates a process. Sends the process a SIGTERM, which does not absolutely guarantee that it will exit. Closes any Handles that were created for the process through Cliff, and terminates any associated background threads that were moving data to and from the process. Use this function this with bracket to ensure proper cleanup of resources.

Gets the exit code of the process that belongs to the ProcessHandle. Often you can get the exit code through more idiomatic pipes functions, as the various Proxy return the ExitCode. Sometimes though it can be difficult to use the pipes idioms to get the exit code, so this function is here.

Side effects: may block if process has not yet exited.

Creates a new ProcessHandle.

Side effects: Does not create the process right away; instead, creates an IO action that, when run, will create the process. This IO action contains another IO action that, when run, will return the process exit code.

In addition, the IO action will fork a simple thread that will immediately wait for the process. In effect, this means there is immediately a thread that will wait for the process to exit. Because this IO action was created with once, that means only one thread ever does the wait, which avoids a bug in System.Process.

Sends an exception using the exception handler specified in the ErrSpec. Side effects: transmits the Oopsie to the right place; the recipient of the Oopsie might have additional side effects.

Close a handle. Catches any exceptions and passes them to the handler.

Runs in the background an effect, typically one that is moving data from one process to another. For examples of its usage, see Pipes.Cliff.Examples.

Runs in the foreground an effect in the SafeT monad.

Creates a new mailbox and returns Proxy that stream values into and out of the mailbox. Each Proxy is equipped with a finalizer that will seal the mailbox immediately after production or consumption has completed, even if such completion is not due to an exhausted mailbox. This will signal to the other side of the mailbox that the mailbox is sealed.

Also returns an STM action to seal the box manually.

Creates a process, uses it, and terminates it when the last computation ends. Don't try to use any of the process resources after the last computation ends, because the process will already have been terminated. For an example of its use, see standardOutputAndErrorBracketed.

Runs an Effect in the backgroud (typically one that is moving data from one process to another). If the background thread is still running when the second computation ends, the background thread is terminated. For an example of its use, see standardOutputAndErrorBracketed.

I have no idea what this should be. I'll start with a simple small value and see how it works.

Initialize a handle. Returns a computation in the MonadSafe monad. That computation has a registered finalizer that will close a particular handle that is found in the ProcessHandle. As a side effect, the IO action creating the ProcessHandle is viewed, meaning that the process will launch if it hasn't already done so.

Produce values from a process standard output. Process is started if it isn't already.

Given an Async, waits for that thread to finish processing values. When it completes, wait for the process exit code.

Takes all steps necessary to get a Consumer for standard input:

• Creates a Consumer that will consume to the process standard input. This Consumer registers a MonadSafe releaser that will close the handle.
• Creates a mailbox, with a Producer from the mailbox and a Consumer to the mailbox. Each of these Proxy has a MonadSafe releaser that will close the mailbox.
• Spwans a thread to run an Effect that connects the Consumer that is connected to the handle to the Producer from the mailbox. In a typical UNIX pipeline situation (where the process keeps its stdin open as long as it is getting input) this Effect will stop running only when the mailbox is sealed.
• Registers a releaser in the Panel (not in the MonadSafe computation) to destroy the thread; this is in case the user terminates the process.
• Returns a Consumer. The Consumer consumes to the mailbox. This Consumer returns the exit code of this process (but remember that the ultimate result of the Proxy depends on which component terminates first).

Does not register in the MonadSafe an action to cancel the background thread. Data might still be moving to the process even if the Proxy has shut down. Let the thread terminate through mailbox closure or a broken pipe.

Takes all steps necessary to get a Producer for standard input. Sets up a mailbox, runs a conveyor in the background. Then receives streaming data, and then gets the process exit code.

Create a Consumer for standard input.

Create a Producer for standard output.

Create a Producer for standard error.

Create a Consumer for standard input and a Producer for standard output.

Create a Consumer for standard input and a Producer for standard error.

Create a Producer for standard output and a Producer for standard error.

Create a Consumer for standard input, a Producer for standard output, and a Producer for standard error.