class Godot::Channel

Overview

A thread-safe, actor-style communication channel bridging Crystal OS threads, cooperative gameplay fibers, Godot C++ threads, and GDScript coroutines.

Inherits from Godot::RefCounted and registers with ClassDB as GodotChannel.

Concurrency Invariant: In Crystal 1.20+, raw OS threads (Thread.new) do not possess a fiber execution context (Fiber#execution_context is nil). Attempting to suspend an empty unbuffered Crystal Channel(T) on an OS thread raises NilAssertionError. Godot::Channel guarantees safety across all threads by utilizing native OS synchronization (Thread::Mutex + Thread::ConditionVariable) and cooperative yielding (Fiber.yield) on the Main Thread.

Defined in:

libgodot/channel.cr

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from class Godot::RefCounted

destroy : Void destroy, get_reference_count : Int64 get_reference_count, init_ref : Bool init_ref, init_ref? : Bool init_ref?, reference : Bool reference, reference? : Bool reference?, unreference : Bool unreference, unreference? : Bool unreference?

Constructor methods inherited from class Godot::RefCounted

new(pointer : Pointer(Void) = Pointer(Void).null) new

Instance methods inherited from class Godot::Object

==(other : Godot::Object) : Bool
==(other : Nil) : Bool ==, _enter_tree : Void _enter_tree, _exit_tree : Void _exit_tree, _godot_call_tool_button(button_name : String) : Void _godot_call_tool_button, _godot_call_virtual(method_name : String, delta : Float64) : Void _godot_call_virtual, _godot_call_virtual_with_data(method_name : String, args : Pointer(Pointer(Void)), ret : Pointer(Void)) : Void _godot_call_virtual_with_data, _godot_get_property(prop_name : String, ret_ptr : Pointer(Void)) : Void _godot_get_property, _godot_set_property(prop_name : String, val_ptr : Pointer(Void)) : Void _godot_set_property, _physics_process(delta : Float64) : Void _physics_process, _process(delta : Float64) : Void _process, _ready : Void _ready, add_user_signal(signal : String, arguments : Pointer(Void)) : Void add_user_signal, alive? : Bool alive?, await_signal(signal_name : String, timeout_sec : Float64 | Nil = nil) : Array(Variant) await_signal, blocking_signals? : Bool blocking_signals?, call(method : String, *args) : Pointer(Void) call, call_bool(method : String, *args) : Bool call_bool, call_deferred(method : String, *args) : Pointer(Void) call_deferred, call_f64(method : String, *args) : Float64 call_f64, call_i64(method : String, *args) : Int64 call_i64, call_obj(method : String, *args) : Node | Nil call_obj, call_obj_as(type : T.class, method : String, *args) : T | Nil forall T call_obj_as, call_str(method : String, *args) : String call_str, callv(method : String, arg_array : Pointer(Void)) : Pointer(Void) callv, can_translate_messages : Bool can_translate_messages, can_translate_messages? : Bool can_translate_messages?, cancel_free : Void cancel_free, check_alive! : Void check_alive!, class?(godot_class : String) : Bool class?, connect(signal_name : String, flags : Godot::ConnectFlags = ::Godot::ConnectFlags::None, callback : Proc(Array(Variant), Void) | Nil = nil) : SignalSubscription
connect(signal_name : String, flags : Godot::ConnectFlags = ::Godot::ConnectFlags::None, &block : Array(Variant) -> Void) : SignalSubscription
connect(signal_name : Symbol, flags : Godot::ConnectFlags = ::Godot::ConnectFlags::None, &block : Array(Variant) -> Void) : SignalSubscription
connect(signal_name : String, listener_target : Godot::Object, method_name : Symbol, flags : Godot::ConnectFlags = ::Godot::ConnectFlags::None) : SignalSubscription
connect(signal : String, callable : Pointer(Void), flags : Int64 = 0_i64) : Godot::Error connect, connect_one_shot(signal_name : String, &block : Array(Variant) -> Void) : SignalSubscription connect_one_shot, connected?(signal : String, callable : Pointer(Void)) : Bool connected?, destroy : Void destroy, destroyed? : Bool destroyed?, disconnect(signal : String, callable : Pointer(Void)) : Void
disconnect(signal_name : String) : Void disconnect, editor_hint? : Bool editor_hint?, emit_property_list_changed : Void emit_property_list_changed, emit_script_changed : Void emit_script_changed, emit_signal(name : String) : Void
emit_signal(name : String, *args) : Void emit_signal, explicitly_freed? : Bool explicitly_freed?, free : Void free, get(property : String) : Pointer(Void) get, get_class : String get_class, get_incoming_connections : Pointer(Void) get_incoming_connections, get_indexed(property_path : NodePath | String) : Pointer(Void) get_indexed, get_instance_id : Int64 get_instance_id, get_meta(name : String, default : Pointer(Void) | Nil = nil) : Pointer(Void) get_meta, get_meta_list : Pointer(Void) get_meta_list, get_method_argument_count(method : String) : Int64 get_method_argument_count, get_method_list : Pointer(Void) get_method_list, get_property_list : Pointer(Void) get_property_list, get_script : Pointer(Void) get_script, get_signal_connection_list(signal : String) : Pointer(Void) get_signal_connection_list, get_signal_list : Pointer(Void) get_signal_list, get_translation_domain : String get_translation_domain, has_connections(signal : String) : Bool has_connections, has_connections?(signal : String) : Bool has_connections?, has_meta(name : String) : Bool has_meta, has_meta?(name : String) : Bool has_meta?, has_method(method : String) : Bool has_method, has_method?(method : String) : Bool has_method?, has_signal(signal : String) : Bool has_signal, has_signal?(signal_name : String) : Bool has_signal?, has_user_signal(signal : String) : Bool has_user_signal, has_user_signal?(signal : String) : Bool has_user_signal?, hash(hasher) hash, if_alive : self | Nil if_alive, instance_id : UInt64 instance_id, is_blocking_signals : Bool is_blocking_signals, is_blocking_signals? : Bool is_blocking_signals?, is_class(godot_class : String) : Bool is_class, is_class?(godot_class : String) : Bool is_class?, is_connected(signal : String, callable : Pointer(Void)) : Bool is_connected, is_connected?(signal : String, callable : Pointer(Void)) : Bool is_connected?, is_queued_for_deletion : Bool is_queued_for_deletion, is_queued_for_deletion? : Bool is_queued_for_deletion?, is_valid? : Bool is_valid?, link_class_script : Void link_class_script, notification(what : Int64, reversed : Bool = false) : Void notification, notify_property_list_changed : Void notify_property_list_changed, pointer : Pointer(Void) pointer, pointer=(val : Pointer(Void)) pointer=, print(*args) print, printerr(*args) printerr, property_can_revert(property : String) : Bool property_can_revert, property_can_revert?(property : String) : Bool property_can_revert?, property_get_revert(property : String) : Pointer(Void) property_get_revert, property_list_changed : Godot::TypedSignal() property_list_changed, puts(*args) puts, queued_for_deletion? : Bool queued_for_deletion?, remove_meta(name : String) : Void remove_meta, remove_user_signal(signal : String) : Void remove_user_signal, script_changed : Godot::TypedSignal() script_changed, set(property : String, value : Pointer(Void)) : Void set, set_block_signals(enable : Bool) : Void set_block_signals, set_deferred(property : String, value : Pointer(Void)) : Void set_deferred, set_indexed(property_path : NodePath | String, value : Pointer(Void)) : Void set_indexed, set_message_translation(enable : Bool) : Void set_message_translation, set_meta(name : String, value : Pointer(Void)) : Void set_meta, set_script(script : Pointer(Void)) : Void set_script, set_translation_domain(domain : String) : Void set_translation_domain, signal(name : String) : Godot::BoundSignal
signal(sym : Symbol) : Godot::BoundSignal signal, signal_connection_count(signal_name : String) : Int32 signal_connection_count, signal_target_id : UInt64 signal_target_id, to_s(io : IO) : Void to_s, to_string : String to_string, to_unsafe : Pointer(Void) to_unsafe, tr(message : String, context : String = "") : String tr, tr_n(message : String, plural_message : String, n : Int64, context : String = "") : String tr_n

Constructor methods inherited from class Godot::Object

new(pointer : Pointer(Void) = Pointer(Void).null) new

Class methods inherited from class Godot::Object

_godot_has_virtual_method(method_name : String) : Bool _godot_has_virtual_method, find_script_path_for_class(target_cls : String) : String find_script_path_for_class, is_instance_id_valid(id : Int | UInt64) : Bool is_instance_id_valid

Constructor Detail

def self.new(capacity : Int32 = 16) : Channel #

def self.new(pointer : Pointer(Void)) : Channel #

Class Method Detail

def self.await_select(channels : Array(Channel), timeout_sec : Float64 | Nil = nil) : Tuple(Channel, ChannelItem) | Nil #

def self.await_select(*channels : Channel, timeout_sec : Float64 | Nil = nil) : Tuple(Channel, ChannelItem) | Nil #

Cooperative multi-channel await multiplexer for gameplay fibers on the Main Thread. Polls channels with fair round-robin scheduling and yields execution slices with Fiber.yield every frame, returning as soon as any channel delivers data or timeout expires.


def self.select_any(channels : Array(Channel)) : Tuple(Channel, ChannelItem) | Nil #

def self.select_any(*channels : Channel) : Tuple(Channel, ChannelItem) | Nil #

Non-blocking multi-channel multiplexer (select_any). Returns the first channel that has an available item and the item itself, or nil if all provided channels are empty.


def self.select_any(&block : ChannelSelect -> Void) : Bool #

Declarative CSP-style select DSL block


Instance Method Detail

def _godot_call_virtual_with_data(method_name : String, args : Pointer(Pointer(Void)), ret : Pointer(Void)) : Void #

Dispatches generic virtual methods and ClassDB method calls with raw arguments and return buffer


def await_receive(timeout_sec : Float64 | Nil = nil) : ChannelItem | Nil #

Cooperatively awaits an item from the channel inside a Crystal gameplay fiber. Yields execution slices via Fiber.yield each frame, preventing engine starvation.


def call(method : String, *args) : Pointer(Void) #

Dynamic method dispatch for GDScript invocation


def capacity : Int32 #

def capacity=(val : Int32) #

def close : Void #

Closes the channel. Unblocks all waiting senders and receivers and emits signal closed.


def closed? : Bool #

def drain(&block : ChannelItem -> Void) : Int32 #

Non-blockingly yields all currently available items in the channel. Returns the number of items drained.


def drain_all : Array(ChannelItem) #

Non-blockingly drains and returns all currently available items as an Array.


def empty? : Bool #

Returns true if the channel currently holds no items


def full? : Bool #

Returns true if the channel buffer is at full capacity


def is_closed : Bool #

def is_empty : Bool #

def is_full : Bool #

def receive(timeout_sec : Float64 | Nil = nil) : ChannelItem | Nil #

Receives an item from the channel, blocking the calling thread until an item is available. Safe for background OS worker threads (Thread.new, WorkerThreadPool). Do NOT call this on Godot's Main Thread; use #try_receive or #await_receive instead!


def send(val : ChannelItem) : Bool #

Sends an item into the channel, blocking if the channel is full until space becomes available. Returns true on success, or false if the channel was closed. Automatically dispatches signal received on Godot's Main Thread via call_deferred.


def size : Int32 #

Returns the current number of queued items


def try_receive : ChannelItem | Nil #

Non-blocking receive operation. Returns the next queued item, or nil if the channel is empty. Safe to call anywhere, including in _process or timer callbacks on the Main Thread.


def try_send(val : ChannelItem) : Bool #

Sends an item into the channel without blocking. Returns true if successfully enqueued, or false if full or closed.