class

Reference

Inherits Object

Reference is the base class of classes you define in your program. It is set as a class' superclass when you don't specify one:

class MyClass # < Reference
end

A reference type is passed by reference: when you pass it to methods, return it from methods or assign it to variables, a pointer is actually passed.

Invoking new on a Reference allocates a new instance on the heap. The instance's memory is automatically freed (garbage-collected) when the instance is no longer referred by any other entity in the program.

Constructors

new

Source

unsafe_construct(address : Pointer, *args, **opts) : self

Constructs an object in-place at the given address, forwarding args and opts to #initialize. Returns that object.

This method can be used to decouple object allocation from initialization. For example, the instance data might come from a custom allocator, or it might reside on the stack using a type like ReferenceStorage.

address must point to a suitably aligned buffer of at least instance_sizeof(self) bytes.

WARNING: This method is unsafe, as it assumes the caller is responsible for managing the memory at the given address manually.

class Foo
  getter i : Int64
  getter str = "abc"

  def initialize(@i)
  end

  def finalize
    puts "bye"
  end
end

foo_buffer = uninitialized ReferenceStorage(Foo)
foo = Foo.unsafe_construct(pointerof(foo_buffer), 123_i64)
begin
  foo # => #<Foo:0x... @i=123, @str="abc">
ensure
  foo.finalize if foo.responds_to?(:finalize) # prints "bye"
end

Class methods

pre_initialize(address : Pointer)

Performs basic initialization so that the given address is ready for use as an object's instance data. Returns address cast to self's type.

More specifically, this is the part of object initialization that occurs after memory allocation and before calling one of the #initialize overloads. It zeroes the memory, sets up the type ID (necessary for dynamic dispatch), and then runs all inline instance variable initializers.

address must point to a buffer of at least instance_sizeof(self) bytes with an alignment of instance_alignof(self) or above. ReferenceStorage fulfils both requirements.

WARNING: The caller is responsible for managing the memory at the given address, in particular if the memory is not garbage-collectable.

class Foo
  getter i : Int64
  getter str = "abc"

  def initialize(@i)
  end

  def self.alloc_with_libc(i : Int64)
    foo_buffer = LibC.malloc(instance_sizeof(Foo))
    foo = Foo.pre_initialize(foo_buffer)
    foo.i                  # => 0
    foo.str                # => "abc"
    (foo || "").is_a?(Foo) # => true

    foo.initialize(i) # okay
    foo
  end
end

foo = Foo.alloc_with_libc(123_i64)
foo.i # => 123

See also: Reference.unsafe_construct, Struct.pre_initialize.

Source

Instance methods

==(other : self)

Returns true if this reference is the same as other. Invokes same?.

Source

==(other : JSON::Any)

Source

==(other : YAML::Any)

Source

==(other)

Returns false (other can only be a Value here).

Source

dup

Returns a shallow copy of this object.

This allocates a new object and copies the contents of self into it.

Source

hash(hasher)

See Object#hash(hasher)

Source

initialize

Source

inspect(io : IO) : Nil

Appends a String representation of this object which includes its class name, its object address and the values of all instance variables.

class Person
  def initialize(@name : String, @age : Int32)
  end
end

Person.new("John", 32).inspect # => #<Person:0x10fd31f20 @name="John", @age=32>

Source

object_id

Returns a UInt64 that uniquely identifies this object.

The returned value is the memory address of this object.

string = "hello"
string.object_id # => 4460249568

pointer = Pointer(String).new(string.object_id)
string2 = pointer.as(String)
string2.object_id == string.object_id # => true

Source

pretty_print(pp) : Nil

Source

same?(other : Reference) : Bool

Returns true if this reference is the same as other. This is only true if this reference's object_id is the same as other's.

Source

same?(other : Nil)

Returns false: a reference is never nil.

Source

to_s(io : IO) : Nil

Appends a short String representation of this object which includes its class name and its object address.

class Person
  def initialize(@name : String, @age : Int32)
  end
end

Person.new("John", 32).to_s # => #<Person:0x10a199f20>

Source