flux-module(1)

SYNOPSIS

flux module load [--name] [--exec] module [args...]
flux module reload [--name] [--exec] [--force] module [args...]
flux module remove [--force] name
flux module list [-l]
flux module stats [-R] [--clear] name
flux module debug [--setbit=VAL] [--clearbit=VAL] [--set=MASK] [--clear=MASK] name
flux module trace [-f] [-t TYPE,...] [-T topic-glob] [name...]

DESCRIPTION

flux module manages flux-broker(1) modules. Modules are automatically loaded at Flux instance start up (rc1) and unloaded at Flux instance shutdown (rc3) using flux-modprobe(1), which is configured to be aware of module dependencies. flux module is more often used in test or debugging situations.

Broker modules are loaded under a name that is automatically registered as a service endpoint. The name may be derived from the module file name or overridden on the command line. The same module may be loaded multiple times under different names, although not all modules support this. Once loaded, the name is used as a handle for the loaded module instance by the other sub-commands.

Broker modules communicate with other Flux components solely with messages and utilize reactive (event loop) programming for concurrency, which presents challenges for traditional debugging techniques. Therefore flux module provides sub-commands for introspection and message tracing.

Broker modules are often implemented as dynamic shared objects loaded into broker threads, but they may also be loaded into separate processes. This may be necessary for isolation, or to support modules written in languages with their own runtime, such as Python. A module loader process assists with loading such modules, establishing communication with the broker, executing the module, and reporting completion back to the broker's module management framework. The loader is inferred from the module file name suffix, or may be specified on the command line. The following module loaders are provided by flux-core:

module-exec (.so*): Loads a dynamic shared object as a separate process, providing more isolation than direct broker thread loading.
module-python-exec (.py): Loads Python broker modules. The Python file must define either a mod_main() function or a single BrokerModule subclass (see MODULE ENTRY POINT). The BrokerModule base class simplifies writing Python broker modules with decorator-based handler registration.

A small number of modules that are integral to the broker are automatically loaded early in broker start-up. Although hard-wired to a particular name and compiled into the broker executable, these modules otherwise behave like regular broker modules and may be reloaded, traced, and introspected as usual.

COMMANDS

load

Load module, which may be the path to a shared object file (including the .so suffix), the path to a Python file (including the .py suffix), or the basename of either on the FLUX_MODULE_PATH, without the suffix.

When flux module load completes successfully, the new module has entered the running state (see LIST OUTPUT below).

-n, --name=NAME: Override the default module name.

--exec: Force the module to be loaded as a separate process.

--loader=PATH: Specify a module loader path. This option implies --exec and only works when module is a path.

reload

Reload module name. This is equivalent to running flux module remove followed by flux module load.

-f, --force: Suppress failure if module is not loaded and proceed with loading.

-n, --name=NAME: Override the default module name.

--exec: Load the module in a separate process.

--loader=PATH: Specify a module loader path. This option implies --exec and only works when module is a path.

remove

Remove module name.

-f, --force: Suppress failure if module name is not loaded.

--cancel

Call pthread_cancel(3) on a thread or send SIGKILL to a process as appropriate to force a module to terminate. This may be useful if the module is not able to respond to the module shutdown request because it has not returned control to its reactor loop.

Note that broker modules running as threads are created with deferred cancellability. This means that cancellation is only effective if the module thread calls one of the functions listed as a cancellation point in pthreads(7).

list

List the loaded modules.

-l, --long: Include the full DSO path for each module.

stats

Request statistics from module name. A JSON object containing a set of counters for each type of Flux message is returned by default, however the object may be customized on a module basis.

-p, --parse=OBJNAME: OBJNAME is a period delimited list of field names that should be walked to obtain a specific value or object in the returned JSON.

-t, --type=int|double: Force the returned value to be converted to int or double.

-s, --scale=N: Multiply the returned (int or double) value by the specified floating point value.

-R, --rusage=[self|children|thread]: Return a JSON object representing an rusage structure returned by getrusage(2). If specified, the optional argument specifies the query target (default: self).

-c, --clear: Send a request message to clear statistics in the target module.

-C, --clear-all: Broadcast an event message to clear statistics in the target module on all ranks.

debug

Manipulate debug flags in module name. The interpretation of debug flag bits is private to the module and its test drivers.

-C, --clear: Set all debug flags to 0.

-S, --set=MASK: Set debug flags to MASK.

-s, --setbit=VAL: Set one debug flag VAL to 1.

-c, --clearbit=VAL: Set one debug flag VAL to 0.

trace

Display message summaries for messages transmitted and received by the named modules, or all modules if none are named.

Note

Trace requests are accepted for modules before they are loaded. As a consequence, a trace request for a misspelled module name may be accepted, but produce no output.

-f, --full: Include JSON payload in output, if any. Payloads that are not JSON are not displayed.

-T, --topic=GLOB: Filter output by topic string.

-t, --type=TYPE,...: Filter output by message type, a comma-separated list. Valid types are request, response, event, or control.

-L, --color[=WHEN]: Colorize output. The optional argument WHEN can be "always", "never", or "auto". If WHEN is omitted, "always" is used. When the option is not used, the default is "auto", or "never" if NO_COLOR is set to a non-empty value in the environment.

-H, --human: Display human-readable output. See also --color and --delta.

-d, --delta: With --human, display the time delta between messages instead of a relative offset since the last absolute timestamp.

DEBUG OPTIONS

-c, --clear: Set debug flags to zero.

-S, --set=MASK: Set debug flags to MASK. The value may be prefixed with 0x to indicate hexadecimal or 0 to indicate octal, otherwise the value is interpreted as decimal.

-c, --clearbit=MASK: Clear the debug bits specified in MASK without disturbing other bits. The value is interpreted as above.

-s, --setbit=MASK: Set the debug bits specified in MASK without disturbing other bits. The value is interpreted as above.

LIST OUTPUT

The list command displays one line for each unique (as determined by SHA1 hash) loaded module.

Module: The module name.
Idle: Idle times are defined as the number of seconds since the module last sent a request or response message.
State: The state of the module is shown as a single character: I initializing, R running, F finalizing, E exited. A module automatically enters running state when it calls flux_reactor_run(3). It can transition earlier by calling flux_module_set_running().
Service: If the module has registered additional services, the service names are displayed in a comma-separated list.
Path: The full path to the broker module file (only shown with the -l, --long option).

MODULE ENTRY POINT

C broker modules define the following entry point:

int mod_main (void *context, int argc, char **argv);: An entry function.

Python broker modules may define one of the following entry points:

mod_main (h, *args): An entry function called with a flux.Flux handle and any module arguments.
class MyModule(BrokerModule): As a shortcut, a Python module that defines a single BrokerModule subclass and no mod_main() has its entry point synthesized automatically as MyModule(h, *args).run(). If multiple subclasses are present, mod_main() must be defined explicitly to resolve the ambiguity.

RESOURCES

Flux: http://flux-framework.org

Flux RFC: https://flux-framework.readthedocs.io/projects/flux-rfc

Issue Tracker: https://github.com/flux-framework/flux-core/issues

FLUX RFC

5/Flux Broker Modules