streaming-commons-0.2.3.1: Common lower-level functions needed by various streaming data libraries

Safe Haskell | Safe-Inferred
Language | Haskell2010

Data.Streaming.Process

Contents

- Functions
- Specialized streaming types
- Process handle
- Type classes
- Checked processes
- Reexport

Description

A full tutorial for this module is available at: https://github.com/snoyberg/conduit/blob/master/PROCESS.md.

Note that, while the tutorial covers `Data.Conduit.Process`, that module closely follows the present one, and almost all concepts in the tutorial apply here.

Synopsis

- streamingProcess :: (MonadIO m, InputSource stdin, OutputSink stdout, OutputSink stderr) => CreateProcess -> m (stdin, stdout, stderr, StreamingProcessHandle)
- closeStreamingProcessHandle :: MonadIO m => StreamingProcessHandle -> m ()
- data Inherited = Inherited
- data ClosedStream = ClosedStream
- data UseProvidedHandle = UseProvidedHandle
- data StreamingProcessHandle
- waitForStreamingProcess :: MonadIO m => StreamingProcessHandle -> m ExitCode
- waitForStreamingProcessSTM :: StreamingProcessHandle -> STM ExitCode
- getStreamingProcessExitCode :: MonadIO m => StreamingProcessHandle -> m (Maybe ExitCode)
- getStreamingProcessExitCodeSTM :: StreamingProcessHandle -> STM (Maybe ExitCode)
- streamingProcessHandleRaw :: StreamingProcessHandle -> ProcessHandle
- streamingProcessHandleTMVar :: StreamingProcessHandle -> TMVar ExitCode
- class InputSource a
- class OutputSink a
- withCheckedProcess :: (InputSource stdin, OutputSink stderr, OutputSink stdout, MonadIO m) => CreateProcess -> (stdin -> stdout -> stderr -> m b) -> m b
- data ProcessExitedUnsuccessfully = ProcessExitedUnsuccessfully CreateProcess ExitCode
- module System.Process

# Functions

streamingProcess :: (MonadIO m, InputSource stdin, OutputSink stdout, OutputSink stderr) => CreateProcess -> m (stdin, stdout, stderr, StreamingProcessHandle) Source #

The primary function for running a process. Note that, with the exception of `UseProvidedHandle`, the values for `std_in`, `std_out` and `std_err` will be ignored by this function.

Since 0.1.4

closeStreamingProcessHandle :: MonadIO m => StreamingProcessHandle -> m () Source #

Free any resources (e.g. `Handle`s) acquired by a call to `streamingProcess`.

Since: 0.1.16

# Specialized streaming types

data Inherited Source #

Inherit the stream from the current process.

Since 0.1.4

Constructors

Inherited |

#### Instances

Instances details

InputSource Inherited Source # |
Instance details Defined in Data.Streaming.Process Methods isStdStream :: (Maybe Handle -> IO Inherited, Maybe StdStream) Source #
OutputSink Inherited Source # |
Instance details Defined in Data.Streaming.Process Methods osStdStream :: (Maybe Handle -> IO Inherited, Maybe StdStream) Source #

data ClosedStream Source #

Close the stream with the child process.

You usually do not want to use this, as it will leave the corresponding file descriptor unassigned and hence available for re-use in the child process.

Since 0.1.4

Constructors

ClosedStream |

#### Instances

Instances details

InputSource ClosedStream Source # |
Instance details Defined in Data.Streaming.Process Methods isStdStream :: (Maybe Handle -> IO ClosedStream, Maybe StdStream) Source #
OutputSink ClosedStream Source # |
Instance details Defined in Data.Streaming.Process Methods osStdStream :: (Maybe Handle -> IO ClosedStream, Maybe StdStream) Source #

data UseProvidedHandle Source #

Use the `Handle` provided by the `CreateProcess` value. This would allow you, for example, to open up a `Handle` to a file, set it as `std_out`, and avoid any additional overhead of dealing with providing that data to your process.

Since 0.1.4

Constructors

UseProvidedHandle |

#### Instances

Instances details

InputSource UseProvidedHandle Source # |
Instance details Defined in Data.Streaming.Process Methods isStdStream :: (Maybe Handle -> IO UseProvidedHandle, Maybe StdStream) Source #
OutputSink UseProvidedHandle Source # |
Instance details Defined in Data.Streaming.Process Methods osStdStream :: (Maybe Handle -> IO UseProvidedHandle, Maybe StdStream) Source #

# Process handle

data StreamingProcessHandle Source #

Wraps up the standard `ProcessHandle` to avoid the `waitForProcess` deadlock. See the linked documentation from the module header for more information.

Since 0.1.4

waitForStreamingProcess :: MonadIO m => StreamingProcessHandle -> m ExitCode Source #

Blocking call to wait for a process to exit.

Since 0.1.4

waitForStreamingProcessSTM :: StreamingProcessHandle -> STM ExitCode Source #

STM version of `waitForStreamingProcess`.

Since 0.1.4

getStreamingProcessExitCode :: MonadIO m => StreamingProcessHandle -> m (Maybe ExitCode) Source #

Non-blocking call to check for a process exit code.

Since 0.1.4

getStreamingProcessExitCodeSTM :: StreamingProcessHandle -> STM (Maybe ExitCode) Source #

STM version of `getStreamingProcessExitCode`.

Since 0.1.4

streamingProcessHandleRaw :: StreamingProcessHandle -> ProcessHandle Source #

Get the raw `ProcessHandle` from a `StreamingProcessHandle`. Note that you should avoid using this to get the process exit code, and instead use the provided functions.

Since 0.1.4

streamingProcessHandleTMVar :: StreamingProcessHandle -> TMVar ExitCode Source #

Get the `TMVar` storing the process exit code. In general, one of the above functions should be used instead to avoid accidentally corrupting the variable's state..

Since 0.1.4

# Type classes

class InputSource a Source #

Class for all things which can be used to provide standard input.

Since 0.1.4

Minimal complete definition

isStdStream

#### Instances

Instances details

InputSource Handle Source # |
Instance details Defined in Data.Streaming.Process.Internal Methods isStdStream :: (Maybe Handle -> IO Handle, Maybe StdStream) Source #
InputSource ClosedStream Source # |
Instance details Defined in Data.Streaming.Process Methods isStdStream :: (Maybe Handle -> IO ClosedStream, Maybe StdStream) Source #
InputSource Inherited Source # |
Instance details Defined in Data.Streaming.Process Methods isStdStream :: (Maybe Handle -> IO Inherited, Maybe StdStream) Source #
InputSource UseProvidedHandle Source # |
Instance details Defined in Data.Streaming.Process Methods isStdStream :: (Maybe Handle -> IO UseProvidedHandle, Maybe StdStream) Source #

class OutputSink a Source #

Class for all things which can be used to consume standard output or error.

Since 0.1.4

Minimal complete definition

osStdStream

#### Instances

Instances details

OutputSink Handle Source # |
Instance details Defined in Data.Streaming.Process.Internal Methods osStdStream :: (Maybe Handle -> IO Handle, Maybe StdStream) Source #
OutputSink ClosedStream Source # |
Instance details Defined in Data.Streaming.Process Methods osStdStream :: (Maybe Handle -> IO ClosedStream, Maybe StdStream) Source #
OutputSink Inherited Source # |
Instance details Defined in Data.Streaming.Process Methods osStdStream :: (Maybe Handle -> IO Inherited, Maybe StdStream) Source #
OutputSink UseProvidedHandle Source # |
Instance details Defined in Data.Streaming.Process Methods osStdStream :: (Maybe Handle -> IO UseProvidedHandle, Maybe StdStream) Source #

# Checked processes

withCheckedProcess :: (InputSource stdin, OutputSink stderr, OutputSink stdout, MonadIO m) => CreateProcess -> (stdin -> stdout -> stderr -> m b) -> m b Source #

Run a process and supply its streams to the given callback function. After the callback completes, wait for the process to complete and check its exit code. If the exit code is not a success, throw a `ProcessExitedUnsuccessfully`.

NOTE: This function does not kill the child process or ensure resources are cleaned up in the event of an exception from the provided function. For that, please use `withCheckedProcessCleanup` from the `conduit-extra` package.

Since 0.1.7

data ProcessExitedUnsuccessfully Source #

Indicates that a process exited with an non-success exit code.

Since 0.1.7

Constructors

ProcessExitedUnsuccessfully CreateProcess ExitCode |

#### Instances

Instances details

Exception ProcessExitedUnsuccessfully Source # |
Instance details Defined in Data.Streaming.Process Methods toException :: ProcessExitedUnsuccessfully -> SomeException Source # fromException :: SomeException -> Maybe ProcessExitedUnsuccessfully Source # displayException :: ProcessExitedUnsuccessfully -> String Source # backtraceDesired :: ProcessExitedUnsuccessfully -> Bool Source #
Show ProcessExitedUnsuccessfully Source # |
Instance details Defined in Data.Streaming.Process Methods showsPrec :: Int -> ProcessExitedUnsuccessfully -> ShowS Source # show :: ProcessExitedUnsuccessfully -> String Source # showList :: [ProcessExitedUnsuccessfully] -> ShowS Source #

# Reexport

module System.Process