module Godot::SystemIO

Overview

=========================================================================== SystemIO: Low-Level CRT File I/O Safety Primitive

Architectural Rationale & Windows IOCP Thread Isolation:

Standard Crystal File operations on Windows rely on asynchronous I/O completion ports (Crystal::IOCP) and active cooperative Fiber event loops.

When Godot executes GDExtension hooks (such as ResourceFormatLoader, ResourceFormatSaver, WorkerThreadPool jobs, or audio streaming threads), callbacks are executed on native C++ engine threads that are not managed by Crystal's runtime. On these alien threads:

Fiber.current.execution_context is nil.
Crystal's IOCP event loop is not pumping.
Invoking standard File.read or File.write can cause deadlocks, NilAssertionError aborts, or silent engine hangs.

Godot::SystemIO solves this by bypassing Crystal's high-level runtime event loop entirely. It issues direct, synchronous C runtime (fopen, fread, fwrite, fclose, _mkdir) calls. It has zero dependencies on Fiber context, GC thread registration, or LibEvent/IOCP, making it 100% crash-safe across all Godot worker threads and GDExtension background hooks.

Defined in:

libgodot/system_io.cr

Constant Summary

SEEK_END = 2
SEEK_SET = 0

Class Method Summary

.append_file(path : String, content : String) : Bool
Appends the content string to the end of a file on disk.
.copy_file(src : String, dst : String) : Bool
Copies a file from src to dst.
.delete_file(path : String) : Bool
Deletes a file on disk.
.ensure_dir(path : String) : Bool
Ensures all parent directories for path exist on disk.
.file_exists?(path : String) : Bool
Returns true if the file exists on disk and can be opened for reading.
.file_size(path : String) : Int64
Returns the size of the file in bytes, or -1 if the file cannot be opened.
.read_file(path : String) : String
Reads the entire content of a file from disk into a Crystal String safely on any thread.
.read_lines(path : String) : Array(String)
Reads a file line-by-line into an Array of Strings.
.write_file(path : String, content : String) : Bool
Writes the entire content string to a file on disk, overwriting existing files.

Class Method Detail

def self.append_file(path : String, content : String) : Bool #

Appends the content string to the end of a file on disk.

def self.copy_file(src : String, dst : String) : Bool #

Copies a file from src to dst.

def self.delete_file(path : String) : Bool #

Deletes a file on disk.

def self.ensure_dir(path : String) : Bool #

Ensures all parent directories for path exist on disk.

def self.file_exists?(path : String) : Bool #

Returns true if the file exists on disk and can be opened for reading.

def self.file_size(path : String) : Int64 #

Returns the size of the file in bytes, or -1 if the file cannot be opened.

def self.read_file(path : String) : String #

Reads the entire content of a file from disk into a Crystal String safely on any thread.

def self.read_lines(path : String) : Array(String) #

Reads a file line-by-line into an Array of Strings.

def self.write_file(path : String, content : String) : Bool #

Writes the entire content string to a file on disk, overwriting existing files.

lapis