System.Process.CommunicationHandle

CommunicationHandle: a Handle that can be serialised,

data CommunicationHandle

A CommunicationHandle is an operating-system specific representation of a Handle that 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: 1.6.20.0

Instances

Read CommunicationHandle

Defined in System.Process.CommunicationHandle.Internal

Methods

readsPrec :: Int -> ReadS CommunicationHandle

readList :: ReadS [CommunicationHandle]

readPrec :: ReadPrec CommunicationHandle

readListPrec :: ReadPrec [CommunicationHandle]

Show CommunicationHandle

Defined in System.Process.CommunicationHandle.Internal

Methods

showsPrec :: Int -> CommunicationHandle -> ShowS

show :: CommunicationHandle -> String

showList :: [CommunicationHandle] -> ShowS

Eq CommunicationHandle

Defined in System.Process.CommunicationHandle.Internal

Methods

(==) :: CommunicationHandle -> CommunicationHandle -> Bool

(/=) :: CommunicationHandle -> CommunicationHandle -> Bool

Ord CommunicationHandle

Defined in System.Process.CommunicationHandle.Internal

Methods

compare :: CommunicationHandle -> CommunicationHandle -> Ordering

(<) :: CommunicationHandle -> CommunicationHandle -> Bool

(<=) :: CommunicationHandle -> CommunicationHandle -> Bool

(>) :: CommunicationHandle -> CommunicationHandle -> Bool

(>=) :: CommunicationHandle -> CommunicationHandle -> Bool

max :: CommunicationHandle -> CommunicationHandle -> CommunicationHandle

min :: CommunicationHandle -> CommunicationHandle -> CommunicationHandle

openCommunicationHandleRead :: CommunicationHandle -> IO Handle

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

Since: 1.6.20.0

openCommunicationHandleWrite :: CommunicationHandle -> IO Handle

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

Since: 1.6.20.0

closeCommunicationHandle :: CommunicationHandle -> IO ()

Close a CommunicationHandle.

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

Since: 1.6.20.0

Creating CommunicationHandles to communicate with

createWeReadTheyWritePipe :: IO (Handle, CommunicationHandle)

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.

See CommunicationHandle.

Since: 1.6.20.0

createTheyReadWeWritePipe :: IO (CommunicationHandle, Handle)

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.

See CommunicationHandle.

Since: 1.6.20.0

High-level API

readCreateProcessWithExitCodeCommunicationHandle

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: 1.6.20.0