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

namespace eval ${NS}::callback {
    proc new {protoname cmdprefix error_value} {
        # Wraps a script level command into a C function
        #  protoname - the name of a prototype created through the
        #    [prototype function] or [prototype stdcall] commands
        #  cmdprefix - the command prefix that should be invoked when the created
        #    C function is called
        #  error_value - the value that should be returned if the command prefix
        #    raises an exception. This is optional if the function prototype
        #    specifies the `void` return type.
        #
        # The returned function pointer can be invoked through the [call] command
        # but the common usage is for it to be passed to
        # a C function that takes a callback function as an argument.
        #
        # Invoking the function pointer will result in $cmdprefix being called
        # with the additional arguments passed in the invocation. These must
        # match the parameter types of the prototype specified in the callback
        # definition.
        #
        # The type declarations in a prototypes used for callbacks have certain
        # restrictions. These arise because the "data flow" is now from script
        # to the C shared library.
        #
        # The parameter and return type are restricted to be
        # scalar values and strings.
        #
        # * The `out`, `inout` and `retval` annotations are not permitted. This
        # means any values to be returned to the shared library must be
        # through explicit raw pointers.
        #
        # * All pointer type declarations must have the unsafe annotation.
        # Other pointer safety annotations `counted`, `dispose`,
        # `disposeonsuccess` cannot be specified.
        #
        # * The value checking annotations `zero`, `nonzero`, `positive` and
        # `nonnegative` cannot be specified for the prototype return type.
        #
        # * The error handling annotations `errno`, `winerror`, `lasterror`
        # and `onerror` cannot be specified.
        #
        # * The `storeonerror` and `storealways` annotations cannot be
        # specified.
        #
        # When $cmdprefix is called from a C function as a callback, it is executed
        # in the Tcl context from which the C function was called and thus has
        # access to the script level local variables etc.
        #
        # When no longer needed, the callback should be freed with the
        # [callback free] command.
        #
        # Returns a callback function pointer that can be called from C native code.
        #
    }

    proc free {cb} {
        # Frees a callback pointer
        #  cb - a function pointer allocated with [callback new]
    }


    namespace export *
    namespace ensemble create
}
