package obus

  1. Overview
  2. Docs
package obus
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Module OBus_busSource

Message buses management

Well-known instances
Sourceval session : ?switch:Lwt_switch.t -> unit -> t Lwt.t

session ?switch () returns a connection to the user session message bus. Subsequent calls to session will return the same bus. OBus will automatically exit the program when an error happens on the session bus. You can change this behavior by calling OBus_connection.set_on_disconnect.

Sourceval system : ?switch:Lwt_switch.t -> unit -> t Lwt.t

system ?switch () returns a connection to the system message bus. As for session, subsequent calls to system will return the same bus. However, if the connection is closed or crashes, system will try to reopen it.

Creation
Sourceval of_addresses : ?switch:Lwt_switch.t -> OBus_address.t list -> t Lwt.t

Establish a connection with a message bus. The bus must be accessible with at least one of the given addresses

Sourceval register_connection : OBus_connection.t -> unit Lwt.t

Register the given connection to a message bus. It has the side effect of requesting a name to the message bus if not already done.

If the connection is a connection to a message bus, created with one of the function of OBus_connection then register_connection must be called on it before any other functions.

Sourceval exit_on_disconnect : exn -> 'a

Function which exit the program as follow:

  • if exn is a fatal error, it prints a message on stderr and exits the program with an exit code of 1
Peer/proxy helpers
Sourceval get_peer : t -> OBus_name.bus -> OBus_peer.t Lwt.t

get_peer bus name returns the peer owning the bus name name. If the service is not activated and is activable, then it is started

get_proxy bus name path resolves name with get_peer and returns a proxy for the object with path path on this service

Bus names
Sourceval name : t -> OBus_name.bus

Same as OBus_connection.name.

Sourceval names : t -> Set.Make(String).t React.signal

names bus is the signal holding the set of all names we currently own. It raises Invalid_argument if the connection is not a connection to a message bus.

Sourceval hello : t -> OBus_name.bus Lwt.t

hello connection sends an hello message to the message bus, which returns the unique connection name of the connection. Note that if the hello message has already been sent, it will fail.

Sourceexception Access_denied of string

Exception raised when a name cannot be owned due to security policies

Sourcetype request_name_result = [
  1. | `Primary_owner
    (*

    You are now the primary owner of the connection

    *)
  2. | `In_queue
    (*

    You will get the name when it will be available

    *)
  3. | `Exists
    (*

    Somebody else already have the name and nobody specified what to do in this case

    *)
  4. | `Already_owner
    (*

    You already have the name

    *)
]
Sourceval request_name : t -> ?allow_replacement:bool -> ?replace_existing:bool -> ?do_not_queue:bool -> OBus_name.bus -> request_name_result Lwt.t

Request a name to the bus. This is the way to acquire a well-know name.

All optional parameters default to false, their meaning are:

  • allow_replacement: allow other application to steal this name from you
  • replace_existing: replace any existing owner of the name
  • do_not_queue: do not queue if not available
Sourcetype release_name_result = [
  1. | `Released
  2. | `Non_existent
  3. | `Not_owner
]
Service starting/discovering
Sourceexception Service_unknown of string

Exception raised when a service is not present on a message bus and can not be started automatically

Sourcetype start_service_by_name_result = [
  1. | `Success
  2. | `Already_running
]
Sourceval start_service_by_name : t -> OBus_name.bus -> start_service_by_name_result Lwt.t

Start a service on the given bus by its name

Sourceval name_has_owner : t -> OBus_name.bus -> bool Lwt.t

Returns true if the service is currently running, i.e. some application offers it on the message bus

Sourceval list_names : t -> OBus_name.bus list Lwt.t

List names currently running on the message bus

Sourceval list_activatable_names : t -> OBus_name.bus list Lwt.t

List services that can be activated. A service is automatically activated when you call one of its method or when you use start_service_by_name

Sourceexception Name_has_no_owner of string
Sourceval get_name_owner : t -> OBus_name.bus -> OBus_name.bus Lwt.t

Return the connection unique name of the given service. Raise a Name_has_no_owner if the given name does not have an owner.

Sourceval list_queued_owners : t -> OBus_name.bus -> OBus_name.bus list Lwt.t

Return the connection unique names of the applications waiting for a name

Messages routing

Note that you should prefer using OBus_match.export and OBus_match.remove since they do not add duplicated rules several times.

Sourceexception Match_rule_invalid of string

Exception raised when the program tries to send an invalid match rule. This should never happen since values of type OBus_match.rule are always valid.

Sourceval add_match : t -> OBus_match.rule -> unit Lwt.t

Add a matching rule on a message bus. This means that every message routed on the message bus matching this rule will be sent to us.

It can raise OBus_error.No_memory.

Sourceexception Match_rule_not_found of string
Sourceval remove_match : t -> OBus_match.rule -> unit Lwt.t

Remove a match rule from the message bus. It raises Match_rule_not_found if the rule does not exists

Other

These functions are also offered by the message bus

Sourceexception Adt_audit_data_unknown of string
Sourceexception Selinux_security_context_unknown of string
Sourceval update_activation_environment : t -> (string * string) list -> unit Lwt.t
Sourceval get_connection_unix_user : t -> OBus_name.bus -> int Lwt.t
Sourceval get_connection_unix_process_id : t -> OBus_name.bus -> int Lwt.t
Sourceval get_adt_audit_session_data : t -> OBus_name.bus -> string Lwt.t
Sourceval get_connection_selinux_security_context : t -> OBus_name.bus -> string Lwt.t
Sourceval reload_config : t -> unit Lwt.t
Sourceval get_id : t -> OBus_uuid.t Lwt.t
Signals

This signal is emitted each time the owner of a name (unique connection name or service name) changes.

Sourceval name_acquired : t -> OBus_name.bus OBus_signal.t
OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct