flux.core.handle module

class flux.core.handle.Flux(url=_flux._core.ffi.NULL, flags=0, handle=None)

Bases: Wrapper

The general Flux handle class, create one of these to connect to the nearest enclosing flux instance

Example

>>> flux.Flux()
<flux.core.Flux object at 0x...>
Parameters

  • uri (str) -- A fully-qualified native path as returned by flux-uri(1), or a path-like string that references any ancestor in the current hierarchy, e.g. / refers to the root instance, .. refers to the parent, ../.. the parent's parent and so on. See flux_open(3) for more details.

  • flags (int) -- flags as described in flux_open(3).

add_watcher(watcher)

Add a reference to a watcher so it avoids garbage collection

attr_get(attr_name)
attr_remove(attr)

Remove a broker attribute :param attr: attribute to remove :type attr: str

Raises

  • ValueError -- attr is not a string.

  • OSError -- failure in underlying RPC call.

attr_set(attr, value)

Set a broker attribute :param attr: attribute to set :type attr: str :param value: attribute value. :type value: str

Raises

  • ValueError -- either attr or value are not strings.

  • OSError -- failure in underlying flux_attr_set(3) API call.

check_watcher_create(callback, args=None)
close()

The underlying flux handle is automatically closed when a Flux instance is deconstructed. Prevent users from manually closing, the handle, leading to a double free.

conf_get(key=None, default=None, update=False)

Access Flux configuration via this handle. On first use, the configuration is fetched synchronously from the broker, then cached in this Flux object. To force the configuration to be updated, pass update=True.

Example: >>> print(handle.conf_get("tbon.topo", default="kary:32"))

Parameters

  • key (str) -- key to get from configuration in dotted-string form, e.g. tbon.topo. If None, then the entire config will be returned. Default is None.

  • default (obj) -- value to return if key is not set. (default=None)

  • update (bool) -- Force an update of the internal conf dict. (default=False)

del_watcher(watcher)

Remove ref to watcher so it is eligible for garbage collection

event_create(topic, payload=None)

Create a new event message.

Parameters

  • topic -- A string, the event's topic

  • payload -- If a string, the payload is used unmodified, if it is another type json.dumps() is used to stringify it

event_recv(topic=None)
event_send(topic, payload=None)

Create and send a new event in one step

event_subscribe(topic)

Subscribe to events

Parameters

topic (str, bytes, or unicode) -- The event's topic to subscribe to

Raises

  • EnvironmentError -- if the topic is None or NULL

  • TypeError -- if the topic is not a str, bytes, or unicode

fd_watcher_create(fd_int, callback, events=None, args=None)
get_rank()
idle_watcher_create(callback=None, args=None)
in_reactor()
log(level, fstring)

Log to the flux logging facility

Parameters

  • level -- A syslog log-level, check the syslog module for possible values

  • fstring -- A string to log, C-style formatting is not supported

msg_watcher_create(callback, type_mask=<bound method Wrapper.__getattr__.<locals>.wrap_class of <flux.core.inner.Core object>>, topic_glob='*', args=None, match_tag=<bound method Wrapper.__getattr__.<locals>.wrap_class of <flux.core.inner.Core object>>, rolemask=None)
prepare_watcher_create(callback, args=None)
classmethod raise_if_exception()

Re-raise any class global exception if set

If a global exception is currently set for the Flux handle class, re-raise it and reset the exception state to None.

The exception is raised from None to preserve the original stack trace.

classmethod reactor_enter()
classmethod reactor_exit()
reactor_run(reactor=None, flags=0)

Run reactor associated with this Flux handle or reactor argument if it is provided. Sets a signal watcher for SIGINT to return from the reactor on Ctrl-C, and raise KeyboardInterrupt.

classmethod reactor_running()

Return True if this thread is running the Flux reactor

reactor_stop(reactor=None)
reactor_stop_error(reactor=None)
recv(type_mask=<bound method ? of <flux.core.inner.Core object>>, match_tag=<bound method ? of <flux.core.inner.Core object>>, topic_glob=None, flags=0)

Receive a message, returns a flux.Message containing the result or None

respond(message, payload=None)

Respond to a flux rpc

Parameters

  • message (Message) -- The message to respond to

  • payload (None, str, bytes, unicode, or json-serializable) -- The (optional) payload to include in the response

rpc(topic, payload=None, nodeid=<bound method ? of <flux.core.inner.Core object>>, flags=0)

Create a new RPC object

send(message, flags=0)

Send a pre-constructed flux message

service_register(name)
service_unregister(name)
classmethod set_exception(exception)

Set a global, per-thread exception for Flux

This class method allows Python callbacks called from the Flux reactor to set a global exception which can be re-thrown after the return to Python (when reactor_run() returns). This is implemented as a class attribute since the Flux handle object which is available in a Python callback from C will be a different instantiation than the Flux handle object which started the reactor (with the same underlying flux_t however)

Parameters

exception (Exception) -- A reference to the exception thrown.

Returns

The previously set exception, or None

Return type

Exception

signal_watcher_create(signum, callback, args=None)
timer_watcher_create(after, callback, repeat=0.0, args=None)
tls = <_thread._local object>