Home
Getting Started
Current Status
Documentation
- frostc
- Syntax
  - Keywords
  - Statements
    - Assignment
    - Method Calls
    - if
    - for
    - while
    - do
    - loop
    - break
    - continue
    - return
    - assert
    - unreachable
    - match
    - try
  - Expressions
  - Annotations
  - Comments
  - Documentation Comments
  - Error Handling
- Classes
  - Interfaces
  - Choices
  - Values
  - Immutability
  - Packages
    - Uses
  - Generics
  - Bare Code
- Methods
- Fields
- Types
- Variables and Constants
- Memory
  - Weak References
- Threads
API Documentation
- frostcollections Array Collection CollectionView CollectionWriter DefaultHashMap HashKey HashMap HashSet IdentityMap IdentitySet ImmutableArray Iterable Iterator List ListView ListWriter Map MapView MapWriter Stack core Bit Char16 Char32 Char8 Comparable Equatable Error Formattable Immutable Int Int16 Int32 Int64 Int8 Matcher Maybe MutableString Index MutableValue Object Range Real32 Real64 RegularExpression SteppedRange String Index Match System Process UInt UInt16 UInt32 UInt64 UInt8 Value Weak io ByteOrder Console File IndentedOutputStream InputStream LineNumberInputStream MemoryInputStream MemoryOutputStream OutputStream PushbackInputStream math Random XorShift128Plus threads Lock MessageQueue Notifier ScopedLock Thread time Timer unsafe Pointer UnsafeMessageQueue

frost.unsafe

Class Pointer<T>

└ Value

└ Immutable

└ Object

Represents a system-level pointer to a block of memory. Pointers are inherently unsafe, bringing all of the standard dangers of C pointers with them into Frost. They are primarily used internally by Frost in the implementation of various data structures, and should generally be avoided in favor of these high-level data structures.

The normal rules for typecasting do not apply to Pointers. A Pointer of any type may be cast into a Pointer of any other type. Since non-value types are represented internally as pointers, a Pointer to a non-value type (such as Pointer<Object>) is actually a pointer to a pointer to an Object. This means it is safe to cast e.g. Pointer<Object> to Pointer<String>, or vice versa, despite the fact that String and Object are different sizes (so long as the underlying objects being pointed to are in fact Strings, of course).

Source Code:: View Source

Class Method Summary

alloc(count:Int):Pointer<T>: Allocates a zero-filled block of memory big enough to hold count instances of its type and returns a pointer to it.

Initializer Summary

init(value:UInt):Pointer<T>: Creates a pointer with a specific integer value.

Field Summary

asUInt:UInt

Inherited Fields:

toString

Instance Method Summary

get():T: Returns the item pointed to by this pointer.
set(value:T): Replaces the item pointed to by this pointer with a new value.
-- index operator -- [](index:Int):T: Returns the n'th item pointed to by this pointer.
-- indexed assignment operator -- []:=(index:Int, value:T): Replaces the n'th item pointed to by this pointer.
realloc(oldCount:Int, newCount:Int):Pointer<T>: Changes the size of the block of memory pointed to by this pointer, equivalent to the C realloc function.
-- add operator -- +(count:Int):Pointer<T>: Moves this pointer forward (or backward if count is negative) count steps.
-- subtract operator -- -(count:Int):Pointer<T>: Moves this pointer backward (or forward if count is negative) count steps.
destroy(): Frees the block of memory that this pointer points to.
clear(): If the pointer points to a reference counted object type, unrefs the object this pointer points to.
clear(index:Int): If the pointer points to a reference counted object type, unrefs the indicated slot and sets it to null.

Initializers


init
(value:UInt
):Pointer<T>

Creates a pointer with a specific integer value.

Parameters:: value - value of type UInt

Fields

property asUInt:UInt

Class Methods

@class

method alloc

(count:Int
):Pointer<T>

Allocates a zero-filled block of memory big enough to hold count instances of its type and returns a pointer to it. For instance, Pointer<Int64>.alloc(8) is equivalent to the C code calloc(sizeof(int64_t), 8).

Parameters:: count - value of type Int

Instance Methods


function get

():T

Returns the item pointed to by this pointer. Equivalent to pointer[0].


method set

(value:T)

Replaces the item pointed to by this pointer with a new value. Equivalent to pointer[0] := value. For reference counted values, this handles unreffing the previous value and reffing the new value automatically.

Parameters:: value - value of type T

-- index operator --

function []

(index:Int
):T

Returns the n'th item pointed to by this pointer. Equivalent to pointer.offset(count).get().

Parameters:: index - value of type Int

-- indexed assignment operator --

method []:=

(index:Int,
 value:T)

Replaces the n'th item pointed to by this pointer. Equivalent to pointer.offset(count).set(value). For reference counted values, this handles unreffing the previous value and reffing the new value automatically.

Parameters:: index - value of type Int
value - value of type T


method realloc

(oldCount:Int,
 newCount:Int
):Pointer<T>

Changes the size of the block of memory pointed to by this pointer, equivalent to the C realloc function. Just as with realloc, the original pointer is invalid after this call and the returned pointer (which may or not be the same) must be used instead.

Parameters:: oldCount - value of type Int
newCount - value of type Int

-- add operator --

function +

(count:Int
):Pointer<T>

Moves this pointer forward (or backward if count is negative) count steps. Each step is the size of a single element of type T, rounded up to its alignment, so e.g. offsetting an Int32 pointer by 4 steps will generally move it by 16 total bytes. This call is not bounds-checked, and moving the pointer outside of its associated block of memory can lead to undefined behavior.

Parameters:: count - value of type Int

-- subtract operator --

function -

(count:Int
):Pointer<T>

Moves this pointer backward (or forward if count is negative) count steps. Each step is the size of a single element of type T, rounded up to its alignment, so e.g. offsetting an Int32 pointer by 4 steps will generally move it by 16 total bytes. This call is not bounds-checked, and moving the pointer outside of its associated block of memory can lead to undefined behavior.

Parameters:: count - value of type Int


method destroy

()

Frees the block of memory that this pointer points to. This is exactly equivalent to the C free function, and in particular **does not do any reference counting or cleanup of values in the pointed-to memory**. If, for instance, you wish to destroy a Pointer<Pointer<Char8>>, you must first destroy all of the inner Pointer<Char8>s or you will leak memory. If the values pointed to by the pointer are reference counted objects, you must call Frost.unref() (or use clear(Int)) to unref them.


method clear

()

If the pointer points to a reference counted object type, unrefs the object this pointer points to. Otherwise, does nothing. This is used to permit safe handling of references from within generic types which do not know whether or not they are dealing with a reference-counted type.


method clear

(index:Int)

If the pointer points to a reference counted object type, unrefs the indicated slot and sets it to null. Otherwise, does nothing. This is used to permit safe handling of references from within generic types which do not know whether or not they are dealing with a reference-counted type. This is equivalent to (pointer + index).clear().

Parameters:: index - value of type Int