---

6.1 Locations programming interface ¶

In this chapter we use the underscore syntax as defined in The underscore syntax.

Function: mbfl_location_enter ¶

Enter into a new location. Initialise the internal state.

Function: mbfl_location_leave ¶

Leave the current location. Run all the registered handlers in reverse order. Return the return status of the last command executed before the call to this function ($?). If this function is called when no location exists: nothing happens.

Before running the handlers the state of the current location is removed from the script’s state.

Preprocessor Macro: mbfl_location_leave_then_return_failure ¶

Expand as follows:

mbfl_location_leave_then_return_failure
→ { mbfl_location_leave ; return_because_failure ; }

Function: mbfl_location_handler HANDLER_SCRIPT ¶

Function: mbfl_location_handler HANDLER_SCRIPT IDVAR ¶

Register a new handler in the current location.

If the optional parameter IDVAR is present: it must be the name of a shell variable; this function stores in that variable a string representing the identifier of the newly added handler; later, we can use the identifier to remove the handler from the location.

It is an error if this function is called outside a location: an exceptional–condition of class mbfl_outside_location_condition is raised; Invalid operation outside location exceptional–condition objects.

Function: mbfl_location_maker_handler HANDLER_SCRIPT ¶

Register a new handler in the current location.

If the optional parameter IDVAR is present: it must be the name of a shell variable; this function stores in that variable a string representing the identifier of the newly added handler; later, we can use the identifier to remove the handler from the location.

It is an error if this function is called outside a location: an exceptional–condition of class mbfl_outside_location_condition is raised; Invalid operation outside location exceptional–condition objects.

Maker handlers are executed only if mbfl_location_leave() is called after a command that exited with non–zero status; otherwise they are skipped. This is a scenario that happens in object constructors:

• some asynchronous resources “belong” to the constructor and must be released when the constructor returns, either successfully or because of an error;
• other asynchronous resources “belong” to the constructed object and must be released only when the constructor fails.

Usage example:

mbfl_location_enter
{
    mbfl_location_maker_handler 'do_stuff'
    do_something

    # By  setting the  location  exit status  to  1 we  tell
    # "mbfl_location_leave" to trigger  the execution of the
    # maker handlers.
    false
}
mbfl_location_leave

Function: mbfl_location_remove_handler_by_id HANDLER_SCRIPT HANDLER_ID ¶

Remove, from the current location, the previously registered handler whose identifier is IDVAR. When successful: return true. If HANDLER_ID is not a handler’s identifier: return false, but nothing else happens.

Function: mbfl_location_run_all ¶

Run all the handlers unwinding all the locations. This is useful as atexit handler, Running scripts at exit–time.

Function: mbfl_location_hook_var HOOK_RV ¶

When called inside a location: store in the result variable HOOK_RV the hook associated to the current location, then return true; otherwise return false.

mbfl_location_enter
{
    mbfl_declare_varref(HOOK_RV)

    if ! mbfl_location_hook_var _(HOOK_RV)
    then return_failure
    fi

    mbfl_hook_add $HOOK_RV my_handler_one

    mbfl_declare_nameref(HOOK, $HOOK_RV)
    mbfl_hook_add _(HOOK) my_handler_two
}
mbfl_location_leave

We can use this function to add handlers to some outer location:

function outer () {
    mbfl_location_enter
    {
        mbfl_declare_varref(OUTER_LOCATION_HOOK)
        mbfl_location_hook_var _(OUTER_LOCATION_HOOK)

        mbfl_location_handler my_handler_one
        inner $OUTER_LOCATION_HOOK
        do_some_thing
    }
    mbfl_location_leave
}

function inner () {
    mbfl_mandatory_parameter(OUTER_LOCATION_HOOK, 1, outer hook)

    mbfl_location_enter
    {
        mbfl_location_handler my_handler_two
        mbfl_hook_add $OUTER_LOCATION_HOOK my_handler_three
        do_some_other_thing
    }
    mbfl_location_leave
}