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

namespace eval ${NS}::pointer {
    proc address {pointer} {
        # Returns the address component of the pointer.
        #  pointer - pointer whose address component is to be returned.
    }
    proc check {pointer} {
        # Validates a pointer and raise an exception if invalid.
        #  pointer - pointer to be validated
        # For a pointer to be treated as valid,
        #
        # - it must not be NULL
        # - it must be registered
        # - if it is tagged, the tag must be the same as that of the registration.
        #
        # If any of the above conditions is not met, an error exception is raised.
        # Note that if $pointer is untagged, the tag of the registration is not
        # checked.
        #
        # See [Pointers][::Concepts::Pointers] for more on pointer
        # safety and registration.
    }
    proc cast {pointer tag} {
        # Casts a pointer to a new tag.
        #  pointer - pointer to be cast
        #  tag - new tag to apply. This will be qualified with the current scope
        #    if not fully qualified.
        #
        # Synopsis: pointer ?TAG?
        #
        # The cast will fail if the `TAG` is not castable to or from the
        # pointer's tag. See [Casting pointers].
        #
        # If `TAG` is not specified, any existing tag is removed from the pointer
        # (effectively marking it as a `void*` pointer).
        #
        # Returns a pointer with the same address and new tag
    }
    proc castable {subtag supertag} {
        # Specifies that pointers with tag $subtag are acceptable in declarations
        # that require $supertag.
        #  subtag - tag which is to be marked as acceptable wherever $supertag
        #    is expected. Will be qualified with current scope if necessary.
        #  supertag - tag which should accept $subtag tagged pointers.
        #    Will be qualified with current scope if necessary.
        #
        # See [Casting pointers] for more information.
    }
    proc castables {} {
        # Returns a list of tags that have been marked as castable with the
        # [pointer castable] command..
    }
    proc counted {pointer} {
        # Registers a pointer as a counted pointer
        #  pointer - pointer to be registered
        # A counted pointer may be registered multiple times. An error
        # is raised if the pointer is NULL or already registered as
        # an uncounted pointer.
        #
        # See [Pointers][::Concepts::Pointers] for more on counted
        # pointers and registration.
    }
    proc dispose {pointer} {
        # Unregisters a safe or counted pointer
        #  pointer - pointer to be unregistered
        # Note that the command only unregisters the pointer. It does
        # not do anything in terms of releases any resources associated
        # with the pointer.
        #
        # An error is raised if the pointer is not registered unless it
        # is a null pointer in which case it is ignored without error.
        #
        # See [Pointers][::Concepts::Pointers] for more on pointer
        # safety and registration.
    }
    proc isnull {pointer} {
        # Returns true if the pointer is a NULL pointer, false otherwise.
        #  pointer - pointer to be checked
    }
    proc isvalid {pointer} {
        # Validates a pointer.
        #  pointer - pointer to be validated
        # For a pointer to be treated as valid,
        #
        # - it must not be NULL
        # - it must be registered
        # - if it is tagged, the tag must be the same as that of the registration.
        #
        # Return a boolean true value if all the above conditions are met,
        # otherwise false.
        #
        # See [Pointers][::Concepts::Pointers] for more on pointer
        # safety and registration.
    }
    proc list {args} {
        # Returns a list of registered pointers optionally filtered by a tag.
        #   args - if specified, must be a single argument which is a tag.
        #     Only pointers matching the tag are returned.
    }
    proc make {address tag} {
        # Return a pointer for a memory address
        #  address - memory address as a positive integer
        #  tag - If not fully qualified, this will be qualified
        #   with the current namespace name.
        #
        # The returned pointer is not registered as safe. The caller
        # can use the [pointer safe] command to mark it as such if so desired.
        #
        # Synopsis: address ?tag?
    }
    proc safe {pointer} {
        # Registers a pointer as a safe uncounted pointer
        #  pointer - pointer to be registered
        # An error is raised if the pointer is already registered
        # or is a NULL pointer.
        #
        # See [Pointers][::Concepts::Pointers] for more on pointer
        # safety and registration.
    }
    proc tag {pointer} {
        # Returns the pointer tag
        #  pointer - pointer whose tag is to be returned.
        # An empty string is returned if the pointer is not tagged.
        #
        # See [Pointers][::Concepts::Pointers] for more on pointer tags.
    }
    namespace export *
    namespace ensemble create
}
