process-1.6.25.0: Process libraries
Safe HaskellNone
LanguageHaskell2010

System.Process.CommunicationHandle

Synopsis

CommunicationHandle: a Handle that can be serialised,

data CommunicationHandle Source #

Gets a GHC Handle File description from the given OS Handle or POSIX fd.

A CommunicationHandle is an abstraction over operating-system specific internal representation of a Handle, which can be communicated through a command-line interface.

In a typical use case, the parent process creates a pipe, using e.g. createWeReadTheyWritePipe or createTheyReadWeWritePipe.

  • One end of the pipe is a Handle, which can be read from/written to by the parent process.
  • The other end is a CommunicationHandle, which can be inherited by a child process. A reference to the handle can be serialised (using the Show instance), and passed to the child process. It is recommended to close the parent's reference to the CommunicationHandle using closeCommunicationHandle after it has been inherited by the child process.
  • The child process can deserialise the CommunicationHandle (using the Read instance), and then use openCommunicationHandleWrite or openCommunicationHandleRead in order to retrieve a Handle which it can write to/read from.

readCreateProcessWithExitCodeCommunicationHandle provides a high-level API to this functionality. See there for example code.

Since: process-1.6.20.0

openCommunicationHandleRead :: CommunicationHandle -> IO Handle Source #

Turn the CommunicationHandle into a Handle that can be read from in the current process.

The returned Handle does not have any finalizers attached to it; use hClose to close it.

Since: process-1.6.20.0

openCommunicationHandleWrite :: CommunicationHandle -> IO Handle Source #

Turn the CommunicationHandle into a Handle that can be written to in the current process.

The returned Handle does not have any finalizers attached to it; use hClose to close it.

Since: process-1.6.20.0

closeCommunicationHandle :: CommunicationHandle -> IO () Source #

Close a CommunicationHandle.

Use this to close the CommunicationHandle in the parent process after the CommunicationHandle has been inherited by the child process.

Since: process-1.6.20.0

Creating CommunicationHandles to communicate with

createWeReadTheyWritePipe :: IO (Handle, CommunicationHandle) Source #

Create a pipe (weRead,theyWrite) that the current process can read from, and whose write end can be passed to a child process in order to receive data from it.

The returned Handle does not have any finalizers attached to it; use hClose to close it.

See CommunicationHandle.

Since: process-1.6.20.0

createTheyReadWeWritePipe :: IO (CommunicationHandle, Handle) Source #

Create a pipe (theyRead,weWrite) that the current process can write to, and whose read end can be passed to a child process in order to send data to it.

The returned Handle does not have any finalizers attached to it; use hClose to close it.

See CommunicationHandle.

Since: process-1.6.20.0

High-level API

readCreateProcessWithExitCodeCommunicationHandle Source #

Arguments

:: NFData a 
=> ((CommunicationHandle, CommunicationHandle) -> CreateProcess)

Process to spawn, given a (read, write) pair of CommunicationHandles that are inherited by the spawned process

-> (Handle -> IO a)

read action

-> (Handle -> IO ())

write action

-> IO (ExitCode, a) 

A version of readCreateProcessWithExitCode that communicates with the child process through a pair of CommunicationHandles.

Example usage:

readCreateProcessWithExitCodeCommunicationHandle
  (\(chTheyRead, chTheyWrite) -> proc "child-exe" [show chTheyRead, show chTheyWrite])
  (\ hWeRead -> hGetContents hWeRead)
  (\ hWeWrite -> hPut hWeWrite "xyz")

where child-exe is a separate executable that is implemented as:

main = do
  [chRead, chWrite] <- getArgs
  hRead  <- openCommunicationHandleRead  $ read chRead
  hWrite <- openCommunicationHandleWrite $ read chWrite
  input <- hGetContents hRead
  hPut hWrite $ someFn input
  hClose hWrite

Since: process-1.6.20.0