# (c) 2023 Ashok P. Nadkarni
# See LICENSE for license terms.

namespace eval ${NS}::arena {
    proc pushframe {sizespec tag} {
        # Pushes a new stack frame on the memory arena.
        #  sizespec - requested size of memory block. This may be specified
        #   either as an integer value or a type specification (optional)
        #  tag - tag for returned pointer if $size is specified (optional)
        # Synopsis: ?size?
        # Synopsis: size ?tag?
        #
        # The command allocate a new frame in the memory arena stack.
        # All allocations from this frame will stay valid only until the
        # corresponding call to [arena popframe].
        #
        # If no arguments are specified, the command initializes an empty frame.
        # Otherwise it allocates storage of $sizespec bytes within the new frame
        # and returns a pointer to it. The size $sizespec may be specified as a
        # positive integer or a CFFI type declaration in which case the memory
        # allocated is that of the type's size.
        #
        # Returns an empty string if not arguments were specified or a safe pointer.
        #
        # See also: "arena allocate" "arena popframe"
    }
    proc popframe {} {
        # Pops the current frame from the memory arena.
        #
        # All allocations from the popped frame are freed and pointers to
        # these unregistered.
    }
    proc allocate {sizespec {tag {}}} {
        # Allocates memory in the current arena frame in the memory arena.
        #  sizespec - requested size of memory block. This may be specified
        #   either as an integer value or a type specification (optional)
        #  tag - tag for returned pointer
        #
        # The allocated memory will stay allocated until the frame is destroyed
        # with [arena popframe]. The size $sizespec may be specified as a
        # positive integer or a CFFI type declaration in which case the memory
        # allocated is that of the type's size.
        #
        # See also: "arena new"
        #
        # Returns a safe pointer to the allocation.
    }
    proc new {typespec initializer {tag {}}} {
        # Allocates memory in the current arena for a type and initializes it.
        #  typespec - a type declaration
        #  initializer - the type-specific value to use to initialize allocated memory.
        #  tag - The optional tag for the returned pointer.
        #
        # The $typespec argument may be any type specificiation. If an
        # array is specified of a larger size than the number of elements
        # in $initializer, the remaining elements are zeroed out.
        #
        # The returned memory will be freed when the arena frame is freed with
        # [arena popframe].
        #
        # See also: "arena allocate"
        #
        # Returns a safe pointer to the allocated memory.
    }

    namespace export *
    namespace ensemble create
}

