10.8 Script branches

The Script Branch API is a set of Python functions for controlling script branches. This API is used when implementing CLI commands that make use of script branches, and also when waiting for simulator events via corresponding wait-for- CLI commands. See the Simics User's Guide for an introduction and examples of using the API.

script_branch Python Module

script_branch.sb_create()

NAME

sb_create — create a script branch

SYNOPSIS

sb_create(func, desc = None)

DESCRIPTION

Create a script branch that will start executing func (which should not take any arguments). The sb_create function returns a unique script-branch identifier, that can be used with sb_interrupt_branch. It may be called from a script branch to create a new parallel branch. The current branch will resume execution when the new script branch is suspended.

The optional desc argument will be displayed by list-script-branches as a description of the script branch.

RETURN VALUE

script-branch identifier

SEE ALSO

script_branch.sb_wait, script_branch.sb_interrupt_branch, script_branch.sb_run_in_main_branch

EXECUTION CONTEXT

Global Context

script_branch.sb_get_wait_id()

NAME

sb_get_wait_id — obtain script branch wait ID

SYNOPSIS

sb_get_wait_id()

DESCRIPTION

Return a new unique script-branch wait-identifier that can be used when suspending a script-branch using sb_wait.

RETURN VALUE

script branch wait-identifier

SEE ALSO

script_branch.sb_wait, script_branch.sb_signal_waiting

script_branch.sb_in_main_branch()

NAME

sb_in_main_branch — indicate if the main branch is running

SYNOPSIS

sb_in_main_branch()

DESCRIPTION

Return true if the main branch is currently active, and not one of the script branches.

SEE ALSO

script_branch.sb_run_in_main_branch

script_branch.sb_interrupt_branch()

NAME

sb_interrupt_branch — interrupt suspended script branch

SYNOPSIS

sb_interrupt_branch(branch_id)

DESCRIPTION

Interrupt a script branch that is currently suspended. The branch_id should be the script-branch identifier (returned by sb_create) of a suspended script branch, otherwise an exception is raised.

As a side effect, the sb_wait function called in the script branch will raise a CliQuietError exception.

SEE ALSO

script_branch.sb_create, script_branch.sb_wait

script_branch.sb_run_in_main_branch()

NAME

sb_run_in_main_branch — run function in the main thread

SYNOPSIS

sb_run_in_main_branch(command, func)

DESCRIPTION

Schedule func (which should not take any arguments) to run in the main thread and block the calling script-branch thread until the function has run. A CliError exception will be raised if an error occurs while running func, otherwise its return value is returned.

RETURN VALUE

return value of func

SEE ALSO

script_branch.sb_create, script_branch.sb_in_main_branch

script_branch.sb_signal_waiting()

NAME

sb_signal_waiting — wake up a suspended script branch

SYNOPSIS

sb_signal_waiting(wait_id)

DESCRIPTION

Wake up a suspended script-branch, with wait_id as wait identifier, letting it run again.

SEE ALSO

script_branch.sb_wait, script_branch.sb_get_wait_id

script_branch.sb_wait()

NAME

sb_wait — suspend a script branch

SYNOPSIS

sb_wait(command, wait_id, reverse=False, always=False, wait_data=None,
        use_obj=None)

DESCRIPTION

Suspend a script branch in the command command (a descriptive string) until sb_signal_waiting is called with wait_id as argument. The reverse and always arguments correspond to the script-branch command arguments with the same names (e.g. see wait-for-breakpoint). The wait_data argument is a string describing the data being waited for, or None. The use_obj argument is deprecated and should never be specified.

SEE ALSO

script_branch.sb_create, script_branch.sb_get_wait_id, script_branch.sb_signal_waiting