Data.Conduit.Process.Unix

Starting processes

forkExecuteFile

Arguments

:: ByteString

command

-> [ByteString]

args

-> Maybe [(ByteString, ByteString)]

environment

-> Maybe ByteString

working directory

-> Maybe (Source IO ByteString)

stdin

-> Maybe (Sink ByteString IO ())

stdout

-> Maybe (Sink ByteString IO ())

stderr

-> IO ProcessHandle

Fork a new process and execute the given command.

This is a wrapper around with fork() and exec*() syscalls, set up to work with conduit datatypes for standard input, output, and error. If Nothing is provided for any of those arguments, then the original file handles will remain open to the child process.

If you would like to simply discard data provided by the child process, provide sinkNull for stdout and/or stderr. To provide an empty input stream, use return ().

Since 0.1.0

killProcess :: ProcessHandle -> IO ()

Kill a process by sending it the KILL (9) signal.

Since 0.1.0

terminateProcess :: ProcessHandle -> IO ()

Attempts to terminate the specified process. This function should not be used under normal circumstances - no guarantees are given regarding how cleanly the process is terminated. To check whether the process has indeed terminated, use getProcessExitCode.

On Unix systems, terminateProcess sends the process the SIGTERM signal. On Windows systems, the Win32 TerminateProcess function is called, passing an exit code of 1.

Note: on Windows, if the process was a shell command created by createProcess with shell, or created by runCommand or runInteractiveCommand, then terminateProcess will only terminate the shell, not the command itself. On Unix systems, both processes are in a process group and will be terminated together.

waitForProcess :: ProcessHandle -> IO ExitCode

Waits for the specified process to terminate, and returns its exit code.

GHC Note: in order to call waitForProcess without blocking all the other threads in the system, you must compile the program with -threaded.

data ProcessStatus

Constructors

Exited ExitCode

Terminated Signal

Stopped Signal

Instances

Eq ProcessStatus

Ord ProcessStatus

Show ProcessStatus

signalProcessHandle :: Signal -> ProcessHandle -> IO ()

signalProcessHandleGroup :: Signal -> ProcessHandle -> IO ()

Process tracking

Ensure that child processes are killed, regardless of how the parent process exits.

The technique used here is:

• Create a pipe.
• Fork a new child process that listens on the pipe.
• In the current process, send updates about processes that should be auto-killed.
• When the parent process dies, listening on the pipe in the child process will get an EOF.
• When the child process receives that EOF, it kills all processes it was told to auto-kill.

This code was originally written for Keter, but was moved to unix-process conduit in the 0.2.1 release.

Types

data ProcessTracker

Represents the child process which handles process cleanup.

Since 0.2.1

data TrackedProcess

Represents a child process which is currently being tracked by the cleanup child process.

Since 0.2.1

data ProcessTrackerException

Since 0.2.1

Constructors

CannotLaunchProcessTracker

Instances

Show ProcessTrackerException

Typeable ProcessTrackerException

Exception ProcessTrackerException

Functions

initProcessTracker :: IO ProcessTracker

Fork off the child cleanup process.

This will ideally only be run once for your entire application.

Since 0.2.1

trackProcess :: ProcessTracker -> ProcessHandle -> IO TrackedProcess

Begin tracking the given process. If the ProcessHandle refers to a closed process, no tracking will occur. If the process is closed, then it will be untracked automatically.

Note that you must compile your program with -threaded; see waitForProcess.

Since 0.2.1

untrackProcess :: TrackedProcess -> IO ()

Explicitly remove the given process from the tracked process list in the cleanup process.

Since 0.2.1

Logging

data RotatingLog

Represents a folder used for totating log files.

Since 0.2.1

openRotatingLog

Arguments

:: FilePath

folder to contain logs

-> Word

maximum log file size, in bytes

-> IO RotatingLog

Create a new RotatingLog.

Since 0.2.1

forkExecuteLog

Arguments

:: ByteString

command

-> [ByteString]

args

-> Maybe [(ByteString, ByteString)]

environment

-> Maybe ByteString

working directory

-> Maybe (Source IO ByteString)

stdin

-> RotatingLog

both stdout and stderr will be sent to this location

-> IO ProcessHandle

Fork and execute a subprocess, sending stdout and stderr to the specified rotating log.

Since 0.2.1

Monitored process

data MonitoredProcess

Abstract type containing information on a process which will be restarted.

monitorProcess

Arguments

:: (ByteString -> IO ())

log

-> ProcessTracker

-> Maybe ByteString

setuid

-> ByteString

executable

-> ByteString

working directory

-> [ByteString]

command line parameter

-> [(ByteString, ByteString)]

environment

-> RotatingLog

-> IO MonitoredProcess

Run the given command, restarting if the process dies.

terminateMonitoredProcess :: MonitoredProcess -> IO ()

Terminate the process and prevent it from being restarted.