View Source Jido.Agent.Syscall (Jido v1.0.0)

Provides a type-safe way to execute system commands that affect agent server behavior.

Overview

Syscalls are immutable instructions that can be executed by the agent server to perform system-level operations like spawning processes, broadcasting messages, etc. Each syscall type is implemented as a separate struct with its own validation rules.

Available Syscalls

  • SpawnSyscall - Spawns a child process under the agent's supervisor

    • Requires a module atom and arguments
    • Example: %SpawnSyscall{module: MyWorker, args: [id: 1]}

  • KillSyscall - Terminates a child process

    • Requires a valid PID
    • Example: %KillSyscall{pid: #PID<0.123.0>}

  • BroadcastSyscall - Broadcasts a message on a PubSub topic

    • Requires a topic string and message
    • Example: %BroadcastSyscall{topic: "events", message: %{type: :update}}

  • SubscribeSyscall - Subscribes to a PubSub topic

    • Requires a topic string
    • Example: %SubscribeSyscall{topic: "events"}

  • UnsubscribeSyscall - Unsubscribes from a PubSub topic

    • Requires a topic string
    • Example: %UnsubscribeSyscall{topic: "events"}

Validation

Each syscall type has its own validation rules to ensure type safety and valid parameters. Failed validation results in an error tuple being returned.

Summary

Types

t()

Functions

is_syscall?(syscall)

Checks if a value is a valid syscall struct.

validate_syscall(arg1)

Validates a syscall struct based on its type.

Types

t()

@type t() ::
  Jido.Agent.Syscall.SpawnSyscall.t()
  | Jido.Agent.Syscall.KillSyscall.t()
  | EnqueueCmdSyscall.t()
  | Jido.Agent.Syscall.BroadcastSyscall.t()
  | Jido.Agent.Syscall.SubscribeSyscall.t()
  | Jido.Agent.Syscall.UnsubscribeSyscall.t()

Functions

is_syscall?(syscall)

@spec is_syscall?(term()) :: boolean()

Checks if a value is a valid syscall struct.

Parameters

  • value: Any value to check

Returns

  • true if the value is a valid syscall struct
  • false otherwise

Examples 

iex> is_syscall?(%SpawnSyscall{module: MyWorker, args: []})
true

iex> is_syscall?(:not_a_syscall)
false

validate_syscall(arg1)

@spec validate_syscall(t()) :: :ok | {:error, term()}

Validates a syscall struct based on its type.

Parameters

  • syscall: The syscall struct to validate

Returns

  • :ok if validation passes
  • {:error, reason} if validation fails

Examples 

iex> validate_syscall(%SpawnSyscall{module: MyWorker, args: []})
:ok

iex> validate_syscall(%SpawnSyscall{module: nil, args: []})
{:error, :invalid_module}