callback (public)

 callback [ -catch ] [ -impl impl ] callback [ args... ]

Defined in packages/acs-bootstrap-installer/tcl/00-proc-procs.tcl

Invoke the registered callback implementations for the given callback. The callbacks terminate on error unless -catch is provided. The value returned by the callback function is determined by the return codes from the callback implementations.

The callbacks are executed one level below the calling function so passing arrays to a callback can be done normally via

upvar arrayname $arrayref

The return codes returned from the implementation are treated as follows:

return -code ok or "return"

With a plain return, a nonempty return value will be lappended to the list of returns from the callback function

return -code error or "error"

errors will simply propagate (and no value returned) unless -catch is specified in which case the callback processing will continue but no value will be appended to the return list for the implementation which returned an error.

return -code return

Takes the return value if the implementation returning -code return and returns a one element list with that return value. Note that this means if you have code which returns return -code return {x y}, you will get {{x y}} as the return value from the callback. This is done in order to unambiguously distinguish a pair of callbacks returning x and y respectively from this single callback.

return -code break

return the current list of returned values including this implementations return value if nonempty

return -code continue

Continue processing, ignore the return value from this implementation

Switches:

-catch (optional, boolean)

if catch specified errors in the callback will be caught, tracebacks logged as errors to the server log, but other callbacks called and the list of returns still returned. If not given an error simply is passed further on.

-impl (optional, defaults to "*")

invoke a specific implementation rather than all implementations of the given callback

Parameters:

callback (required)

the callback name without leading or trailing ::

Returns:

list of the returns from each callback that does a normal (nonempty) return

See Also:

• ad_proc

Partial Call Graph (max 5 caller/called nodes):

Testcases:

ad_proc_create_callback, ad_proc_fire_callback

Source code:

    if {$callback eq ""} {
        error "callback: no callback name given"
    }
    #
    # Check, if the contract exists and call the contract for
    # arg validation -- ::callback::${callback}::contract is an
    # empty function that only runs the ad_proc generated arg parser.

    if {[namespace which ::callback::${callback}::contract] eq ""} {
        if {[ns_ictl epoch] == 0} {
            #
            # During initial startup, a callback implementation might
            # not be loaded yet. Ignore the callback invocation, but
            # inform the admin in the system log about it.
            #
            ns_log notice "callback invocation $callback during startup ignored. "  "The callback implementation might not be loaded yet."
        } else {
            error "Undefined callback $callback"
        }
    }
    ::callback::${callback}::contract {*}$args

    set returns {}

    set base ::callback::${callback}::impl
    foreach procname [lsort [info commands ${base}::$impl]] {
        set c [catch {::uplevel 1 [::list $procname {*}$args]} ret]
        switch -exact $c {
            0 { # code ok
                if { $ret ne "" } {
                    lappend returns $ret
                }
            }
            1 { # code error - either rethrow the current error or log
                if {$catch_p} {
                    set msg "callback $callback error invoking $procname: $ret"
                    if {[aa_test_running_p]} {
                        set severity warning
                    } else {
                        set severity error
                        append msg \n[ad_print_stack_trace]
                    }
                    ns_log $severity $msg
                } else {
                    return -code $c -errorcode $::errorCode -errorinfo $::errorInfo $ret
                }
            }
            2 { # code return -- end processing and return what we got back.
                return [list $ret]
            }
            3 { # code break -- terminate return current list of results.
                if { $ret ne "" } {
                    lappend returns $ret
                }
                return $returns
            }
            4 { # code continue -- just skip this one
            }
            default {
                error "Callback return code unknown: $c"
            }
        }
    }

    if {$impl ne "*" && ![info exists c] && !$catch_p} {
        error "callback $callback implementation $impl does not exist"
    }

    return $returns

XQL Not present:

Generic, PostgreSQL, Oracle