sceall

Types

ProgramHandle

opaque </>

A reference to the spawned program.

pub opaque type ProgramHandle

ProgramMessage

</>

Messages that will be sent to the BEAM process that called the spawn_program function. These can be received using the select function.

pub type ProgramMessage {
  Data(program: ProgramHandle, data: BitArray)
  Exited(program: ProgramHandle, status_code: Int)
}

Constructors

```
Data(program: ProgramHandle, data: BitArray)
```
Data that the program printed to stdout or stderr.

Be aware, data printed could be too large or printed too slowly for one message! In these cases, the data will be delivered over multiple messages.

Exited(program: ProgramHandle, status_code: Int)

The program exited.

SendError

</>

pub type SendError {
  SendWasAborted
  CannotSendToExitedProgram
}

Constructors

```
SendWasAborted
```
The port send operation was aborted
```
CannotSendToExitedProgram
```
The program has already exited

SpawnProgramError

</>

pub type SpawnProgramError {
  NotEnoughBeamPorts
  NotEnoughMemory
  NotEnoughOsProcesses
  ExternalCommandTooLong
  NotEnoughFileDescriptors
  OsFileTableFull
  FileNotExecutable
  FileDoesNotExist
}

Constructors

```
NotEnoughBeamPorts
```
There are not enough beam ports available.
```
NotEnoughMemory
```
There is insufficient memory to spawn the executable.
```
NotEnoughOsProcesses
```
There are not enough OS processes available.
```
ExternalCommandTooLong
```
The external command is too long to execute.
```
NotEnoughFileDescriptors
```
There are not enough file descriptors available.
```
OsFileTableFull
```
The OS file table is full.
```
FileNotExecutable
```
The file at the given path could not be executed.
```
FileDoesNotExist
```
No file exists at the given path.

Values

exit_program

</>

pub fn exit_program(program: ProgramHandle) -> Bool

Exit a program. Returns True if the program was stopped, returns False if the program had already stopped.

The Exited message will not be sent if the program is stopped with this function.kj

find_executable

</>

pub fn find_executable(name: String) -> Result(String, Nil)

Find the path to a program given it’s name.

Returns an error if no such executable could be found in the PATH.

program_port

</>

pub fn program_port(handle: ProgramHandle) -> port.Port

Get the BEAM port for a given program.

select

</>

pub fn select(
  selector: process.Selector(message),
  program: ProgramHandle,
  mapper: fn(ProgramMessage) -> message,
) -> process.Selector(message)

Add a message handler for messages from the spawned program. See ProgramMessage for details.

Use this to handle program messages in your actor!

send

</>

pub fn send(
  program: ProgramHandle,
  data: BitArray,
) -> Result(Nil, SendError)

Send some data to stdin of the program.

Sending is synchronous, with the sending process blocking until the operation completes.

spawn_program

</>

pub fn spawn_program(
  executable_path path: String,
  working_directory directory: String,
  command_line_arguments arguments: List(String),
  environment_variables environment: List(#(String, String)),
) -> Result(ProgramHandle, SpawnProgramError)

Spawn an operating system, returning a reference to it that can be used to receive stdio data as messages.

There is no PATH variable resolution, so you cannot give the name of a program. It must be a path to the executable.

The process that calls this function is the owner of the BEAM port for the spawned program. When this process exits the port and the program will be shut down.