API Reference

@own [:mut] x = value
@own [:mut] x, y, z = (value1, value2, value3)
@own [:mut] for var in iter
    # body
end
@own [:mut] x  # equivalent to @own [:mut] x = x
@own [:mut] (x, y)  # equivalent to @own [:mut] (x, y) = (x, y)

Create a new owned variable. If :mut is specified, the value will be mutable. Otherwise, the value will be immutable.

You may also use @own in a for loop to create an owned value for each iteration.

@move [:mut] new = old

Transfer ownership from one variable to another, invalidating the old variable. If :mut is specified, the destination will be mutable. Otherwise, the destination will be immutable. For isbits types, this will automatically use @clone instead.

@clone [:mut] new = old

Create a deep copy of a value, without moving the source. If :mut is specified, the destination will be mutable. Otherwise, the destination will be immutable.

@take var

Returns the inner value and does a deepcopy. This does not mark the original as moved.

@take! var

Take ownership of a value, typically used in function arguments. Returns the inner value and marks the original as moved. For isbits types, this will return a copy and not mark the original as moved.

@lifetime a begin
    @ref ~a rx = x
    # use refs here
end

Create a lifetime scope for references. References created with this lifetime are only valid within the block and are automatically cleaned up when the block exits.

@ref ~lifetime [:mut] var = value
@ref ~lifetime [:mut] (var1, var2, ...) = (value1, value2, ...)
@ref ~lifetime [:mut] for var in iter
    # body
end

Create a reference to an owned value within a lifetime scope. See the @lifetime macro for more information on lifetime scopes.

If :mut is specified, creates a mutable reference. Otherwise, creates an immutable reference. Returns a Borrowed{T} or BorrowedMut{T} that forwards access to the underlying value.

Mutex{T} <: AbstractMutex{T}

A mutex that protects a value of type T. Provides safe concurrent access to the protected value.

Example

m = Mutex([1, 2, 3])
lock(m)
@ref_into :mut arr = m[]
push!(arr, 4)
unlock(m)

@ref_into [:mut] var = mutex[]

Create a reference to the protected value in a mutex.

If :mut is specified, creates a mutable reference. Otherwise, creates an immutable reference.

Examples

m = Mutex([1, 2, 3])
lock(m) do
    @ref_into :mut arr2 = m[]
    push!(arr2, 4)
end

@bc func(args...; kwargs...)

Calls func with the given arguments and keyword arguments, automatically creating temporary borrows for arguments that appear to be owned variables.

Examples

Say that we wish to safely modify an array by reference. We have two owned variables, ar1 and ar2, and we wish to add the first element of ar2 to ar1.

@own :mut ar1 = [1, 2]
@own ar2 = [3, 4]

add_first!(x, y) = (x[1] += y[1]; nothing)

If we set up a lifetime scope manually, we might write:

@lifetime lt begin
    @ref ~lt :mut ref1 = ar1
    @ref ~lt ref2 = ar2
    add_first!(ref1, ref2)
end

However, most of the time you only need to create a lifetime scope for a single function call, so @bc lets us do this automatically:

@bc add_first!(@mut(ar1), ar2)

This will evaluate to something that is quite similar to the manual lifetime scope.

@bc also supports non-owned variables, which will simply get passed through as-is.

@mut expr

Marks a value to be borrowed mutably in a @bc macro call.

@&(T)
@&(:mut, T)

Type alias macro for borrowed types. @& T expands to Union{T, Borrowed{T}} and @&(:mut, T) expands to Union{T, BorrowedMut{T}} (as well as their LazyAccessor versions).

This is useful for writing generic signatures that accept either a raw value or a borrowed value.

Examples

Here, we define a function that accepts a mutable borrow of a Vector{Int}. We also demonstrate the use of a Mutex to protect the vector.

julia> function foo(x::@&(:mut, Vector{Int}))
           push!(x, 4)
           return nothing
       end
foo (generic function with 1 method)

julia> m = Mutex([1, 2, 3])
Mutex{Vector{Int64}}([1, 2, 3])

julia> lock(m) do
           @ref_into :mut r = m[]
           foo(r)
       end

julia> println(m)
Mutex{Vector{Int64}}([1, 2, 3, 4])

@cc closure_expr

"Closure Check" is a macro that attempts to verify a closure is compatible with the borrow checker.

Only immutable references (created with @ref and @bc) are allowed to be captured; all other owned and borrowed variables that are captured will trigger an error.

Examples

@own x = 1
@own :mut y = 2

@lifetime lt begin
    @ref ~lt z = x
    @ref ~lt :mut w = y
    
    # These error as the capturing breaks borrowing rules
    bad = @cc () -> x + 1
    bad2 = @cc () -> w + 1
    
    # However, you are allowed to capture immutable references
    good = @cc () -> z + 1
    # This will not error.
end

BorrowChecker.@spawn [options...] expr

Threads.@spawn but with @cc applied to the expression to ensure safe captures.

AbstractOwned{T}

Base type for all owned value types.

AbstractBorrowed{T}

Base type for all borrowed reference types.

Owned{T} <: AbstractOwned{T}

An immutable owned value. Common operations:

• Create using @own x = value
• Access value using @take! (moves) or @take (copies)
• Borrow using @ref
• Access fields/indices via .field or [indices...] (returns LazyAccessor)

Once moved, the value cannot be accessed again.

Internal fields (not part of public API):

• value::T: The contained value
• moved::Bool: Whether the value has been moved
• immutable_borrows::Int: Count of active immutable borrows
• symbol::Symbol: Variable name for error reporting

OwnedMut{T} <: AbstractOwned{T}

A mutable owned value. Common operations:

• Create using @own :mut x = value
• Access value using @take! (moves) or @take (copies)
• Modify by setproperty! or setindex!: x.field = value or x[indices...] = value
• Borrow using @ref or @ref :mut
• Access fields/indices via .field or [indices...] (returns LazyAccessor)

Once moved, the value cannot be accessed again.

Internal fields (not part of public API):

• value::T: The contained value
• moved::Bool: Whether the value has been moved
• immutable_borrows::Int: Count of active immutable borrows
• mutable_borrows::Int: Count of active mutable borrows
• symbol::Symbol: Variable name for error reporting

Borrowed{T,O<:AbstractOwned} <: AbstractBorrowed{T}

An immutable reference to an owned value. Common operations:

• Create using @ref lt x = value
• Access value using @take (copies)
• Access fields/indices via .field or [indices...] (returns LazyAccessor)

Multiple immutable references can exist simultaneously. The reference is valid only within its lifetime scope.

Internal fields (not part of public API):

• value::T: The referenced value
• owner::O: The original owned value
• lifetime::Lifetime: The scope in which this reference is valid
• symbol::Symbol: Variable name for error reporting

BorrowedMut{T,O<:OwnedMut} <: AbstractBorrowed{T}

A mutable reference to an owned value. Common operations:

• Create using @ref lt :mut x = value
• Access value using @take (copies)
• Access fields/indices via .field or [indices...] (returns LazyAccessor)

Only one mutable reference can exist at a time, and no immutable references can exist simultaneously.

Internal fields (not part of public API):

• value::T: The referenced value
• owner::O: The original owned value
• lifetime::Lifetime: The scope in which this reference is valid
• symbol::Symbol: Variable name for error reporting

LazyAccessor{T,P,S,O<:Union{AbstractOwned,AbstractBorrowed}} <: AbstractWrapper{T}

A lazy accessor for properties or indices of owned or borrowed values. Maintains ownership semantics while allowing property/index access without copying or moving.

Created automatically when accessing properties or indices of owned/borrowed values:

@own x = (a=1, b=2)
x.a  # Returns a LazyAccessor

Internal fields (not part of public API):

• parent::P: The parent value being accessed
• property::S: The property/index being accessed
• property_type::Type{T}: Type of the accessed property/index
• target::O: The original owned/borrowed value

OrBorrowed{T}

Type alias for accepting either a value of type T or a borrowed reference to it.

OrBorrowedMut{T}

Type alias for accepting either a value of type T or a mutable borrowed reference to it.

is_static(x)

This trait is used to determine if we can safely @take! a value without marking the original as moved.

This is somewhat analogous to the Copy trait in Rust, although because Julia immutables are truly immutable, we actually do not need to copy on these.

For the most part, this is equal to isbits, but it also includes things like Symbol and Type{T} (recursively), which are not isbits, but which are immutable.

abstract type BorrowError <: Exception end

Base type for all errors related to borrow checking rules.

MovedError <: BorrowError

Error thrown when attempting to use a value that has been moved.

BorrowRuleError <: BorrowError

Error thrown when attempting to violate borrow checking rules, such as having multiple mutable references.

SymbolMismatchError <: BorrowError

Error thrown when attempting to reassign a variable without using proper ownership transfer mechanisms.

ExpiredError <: BorrowError

Error thrown when attempting to use a reference whose lifetime has expired.