# Class LittleGhost::Sandbox::ProcessSession

Documentation version: Edge

Canonical HTML: https://littleghostai.org/docs/LittleGhost/Sandbox/ProcessSession.html

Owns one sandboxed child process and its bounded input and output streams.
Timeout, cancellation, and close terminate the original process group and its
ordinary descendants. A descendant that creates another process group can
outlive this session. Use a backend with `process_tree_ownership` or an outer
supervisor when complete descendant ownership is required.

When `memory_bytes` is configured, the parent samples the visible process tree
every 100 milliseconds. This guard may miss memory peaks between samples. On
Linux, three consecutive failures to read the root process or the
`/proc` snapshot end the process. Use an outer cgroup or container
when memory needs a hard kernel-enforced limit.

## Inheritance

`LittleGhost::Sandbox::ProcessSession < Object`

## Attributes

<a id="attribute-i-pid"></a>
### `pid` (R)

Operating-system process ID of the command process.

## Class methods

<a id="method-c-new"></a>
### `.new`

```ruby
.new(command:, environment: {}, inherit_environment: false, chdir: nil,
        output_bytes: 1_000_000, memory_bytes: nil, memory_reader: nil, cpu_seconds: nil, file_bytes: nil)
```

Starts `command` in a new process group with a scrubbed environment by
default. `output_bytes` bounds combined standard output and error. Optional
CPU, file-size, and sampled-memory limits apply to the child.

## Instance methods

<a id="method-i-alive-3F"></a>
### `#alive?`

```ruby
#alive?()
```

Whether the command process or its original process group is still alive.
Raises when resource supervision failed.

<a id="method-i-close"></a>
### `#close`

```ruby
#close()
```

Terminates the process when needed and closes every owned stream. Calling
`close` more than once is safe.

<a id="method-i-close_write"></a>
### `#close_write`

```ruby
#close_write()
```

Closes the child's standard input without ending the process.

<a id="method-i-read"></a>
### `#read`

```ruby
#read(timeout: 0)
```

Reads currently available output, waiting for at most `timeout` seconds.

<a id="method-i-terminate"></a>
### `#terminate`

```ruby
#terminate()
```

Requests termination, forces it when needed, and returns the child's
Process::Status when available.

<a id="method-i-wait"></a>
### `#wait`

```ruby
#wait(timeout: nil, context: nil, terminate: true)
```

Waits for completion and returns the child's Process::Status. When `terminate`
is true, expiry stops the whole process group before raising.

<a id="method-i-write"></a>
### `#write`

```ruby
#write(value)
```

Writes `value` to the child's standard input.