Class: Microsandbox::SandboxHandle

Inherits:
Object
  • Object
show all
Defined in:
lib/microsandbox/sandbox.rb

Overview

A controllable handle to a sandbox, returned by Microsandbox::Sandbox.get, Microsandbox::Sandbox.list, and Microsandbox::Sandbox.list_with. Carries a metadata snapshot (captured when fetched) plus the fine-grained lifecycle surface — ‘stop_with_timeout`, `request_stop`, `request_kill`, `request_drain`, `wait_until_stopped` — that mirrors the official SDKs’ ‘SandboxHandle`. (The live Sandbox from Microsandbox::Sandbox.create/ Microsandbox::Sandbox.start carries only the high-level `stop`/`kill`/`drain`/`wait`.)

As of v0.5.8 this replaces the old read-only ‘SandboxInfo` (kept as a deprecated constant alias); `#status` here is a synchronous snapshot.

Instance Method Summary collapse

Constructor Details

#initialize(native) ⇒ SandboxHandle

Returns a new instance of SandboxHandle.



14
15
16
 
# File 'lib/microsandbox/sandbox.rb', line 14

def initialize(native)
  @native = native
end

Instance Method Details

#created_at ⇒ Time?

Returns:

  • (Time, nil) 


33
34
35
36
 
# File 'lib/microsandbox/sandbox.rb', line 33

def created_at
  ms = @native.created_at_ms
  ms && Time.at(ms / 1000.0)
end

#inspect ⇒ Object 



102
103
104
 
# File 'lib/microsandbox/sandbox.rb', line 102

def inspect
  "#<Microsandbox::SandboxHandle name=#{name.inspect} status=#{status}>"
end

#kill ⇒ nil

Force-kill the sandbox (SIGKILL).

Returns:

  • (nil) 


61
62
63
64
 
# File 'lib/microsandbox/sandbox.rb', line 61

def kill
  @native.kill
  nil
end

#kill_with_timeout(timeout) ⇒ nil

Force-kill, waiting up to ‘timeout` seconds for the process to disappear.

Parameters:

  • timeout (Numeric)

Returns:

  • (nil) 


69
70
71
72
 
# File 'lib/microsandbox/sandbox.rb', line 69

def kill_with_timeout(timeout)
  @native.kill_with_timeout(Sandbox.send(:coerce_duration, timeout, "timeout"))
  nil
end

#name ⇒ String

Returns:

  • (String) 


19
 
# File 'lib/microsandbox/sandbox.rb', line 19

def name = @native.name

#request_drain ⇒ nil

Request a graceful drain (SIGUSR1) and return immediately, without waiting.

Returns:

  • (nil) 


91
92
93
94
 
# File 'lib/microsandbox/sandbox.rb', line 91

def request_drain
  @native.request_drain
  nil
end

#request_kill ⇒ nil

Send the force-kill request and return immediately, without waiting.

Returns:

  • (nil) 


84
85
86
87
 
# File 'lib/microsandbox/sandbox.rb', line 84

def request_kill
  @native.request_kill
  nil
end

#request_stop ⇒ nil

Send the graceful-shutdown request and return immediately, without waiting. Pair with #wait_until_stopped.

Returns:

  • (nil) 


77
78
79
80
 
# File 'lib/microsandbox/sandbox.rb', line 77

def request_stop
  @native.request_stop
  nil
end

#running? ⇒ Boolean

Whether the fetch-time #status snapshot is ‘:running` / `:stopped`. Like #status, these do NOT refresh: to observe a state change after #request_stop/#request_kill/#request_drain, use #wait_until_stopped or re-fetch the handle with Microsandbox::Sandbox.get.

Returns:

  • (Boolean) 


29
 
# File 'lib/microsandbox/sandbox.rb', line 29

def running? = status == :running

#status ⇒ Symbol

Returns :created, :starting, :running, :draining, :paused, :stopped, or :crashed (a snapshot, captured when this handle was fetched).

Returns:

  • (Symbol) —

    :created, :starting, :running, :draining, :paused, :stopped, or :crashed (a snapshot, captured when this handle was fetched)



23
 
# File 'lib/microsandbox/sandbox.rb', line 23

def status = @native.status.to_sym

#stop ⇒ nil

Gracefully stop the sandbox (SIGTERM→SIGKILL escalation, 10s default).

Returns:

  • (nil) 


46
47
48
49
 
# File 'lib/microsandbox/sandbox.rb', line 46

def stop
  @native.stop
  nil
end

#stop_with_timeout(timeout) ⇒ nil

Gracefully stop with a custom escalation timeout.

Parameters:

  • timeout (Numeric) —

    seconds to wait before escalating to SIGKILL

Returns:

  • (nil) 


54
55
56
57
 
# File 'lib/microsandbox/sandbox.rb', line 54

def stop_with_timeout(timeout)
  @native.stop_with_timeout(Sandbox.send(:coerce_duration, timeout, "timeout"))
  nil
end

#stopped? ⇒ Boolean

Returns:

  • (Boolean) 


30
 
# File 'lib/microsandbox/sandbox.rb', line 30

def stopped? = status == :stopped

#updated_at ⇒ Time?

Returns:

  • (Time, nil) 


39
40
41
42
 
# File 'lib/microsandbox/sandbox.rb', line 39

def updated_at
  ms = @native.updated_at_ms
  ms && Time.at(ms / 1000.0)
end

#wait_until_stopped ⇒ SandboxStopResult

Block until the sandbox is observed in a terminal (non-running) state.

Returns:



98
99
100
 
# File 'lib/microsandbox/sandbox.rb', line 98

def wait_until_stopped
  SandboxStopResult.new(@native.wait_until_stopped)
end