ivy.std_api module

Implements the standard Ivy API.

The Tutorial gives an overview of the most important features. You can also refer to the example code pyhello.py for an example of use.

All methods in this module are frontends to a ivy.IvyServer instance, stored in the module’s attribute _IvyServer.

Connecting to/disconnecting from the Ivy bus:

Handling our subscriptions:

Reacting to other types of messages:

IvyBindDirectMsg(), IvyBindPong()/IvySetPongCallback()

Inspecting the Ivy bus:

Interacting with other Ivy clients:

Timers:

ivy.std_api.IvyBindDirectMsg(on_msg_fct: Callable) → None

Registers a method that should be called each time someone sends us a direct message

ivy.std_api.IvyBindMsg(on_msg_fct: Callable, regexp: str) → int

Registers a method that should be called each time a message matching regexps is sent on the Ivy bus.

Returns:

an id identifying the binding, that can be used to unregister it (see IvyUnbindMsg())

ivy.std_api.IvyBindPong(on_pong_fct: Callable) → None

Registers a method that should be called when we receive a PONG message. When receiving a PONG message in replying of a PING message we sent (see IvySendPing()), this method is called with three arguments:

  • the first one is the IvyClient object sorresponding to the agent sending the message;

  • the second one is the time elapsed between the sending of the ping and the receiving of the pong.

ivy.std_api.IvyBindRegexpChange(regexp_change_callback: Callable) → None

Registers a function to be called when an agent adds or removes a binding.

This function will receive 4 parameters: an IvyClient, the event (either IvyRegexpAdded or IvyRegexpRemoved), the identifier of the subscriptions and the regular expression itself (as a string).

ivy.std_api.IvyGetApplication(name: str) → IvyClient | None

Returns the Ivy client registered on the bus under the given name.

Warning

if multiple applications are registered w/ the same name only one is returned

Returns:

an ivy.ivy.IvyClient object

ivy.std_api.IvyGetApplicationHost(client: IvyClient) → str

Equivalent to client.fqdn. IP address is stored under client.ip, and port number under client.port

Parameters:

client – an ivy.ivy.IvyClient object, as returned by IvyGetApplication()

ivy.std_api.IvyGetApplicationList() → List[str]

Returns the names of the applications that are currently connected

ivy.std_api.IvyGetApplicationMessages(client: IvyClient) → List[Tuple[int, str]]

Returns all subscriptions for that client

Parameters:

client – an ivy.ivy.IvyClient object, as returned by IvyGetApplication()

Returns:

list of tuples (idx, regexp)

ivy.std_api.IvyGetApplicationName(client: IvyClient) → str | None

Equivalent to client.agent_name

Parameters:

client – an ivy.ivy.IvyClient object, as returned by IvyGetApplication()

ivy.std_api.IvyGetMessages() → List[Tuple[int, str]]

Returns our subscriptions

Returns:

list of tuples (idx, regexp)

ivy.std_api.IvyInit(agent_name: str, ready_msg: str | None = None, main_loop_type_ignored: int = 0, on_cnx_fct: ~collections.abc.Callable = <function void_function>, on_die_fct: ~collections.abc.Callable = <function void_function>) → None

Initializes the module. This method should be called exactly once before any other method is called.

ivy.std_api.IvyMainLoop() → None

Simulates the original main loop: simply waits for the server termination.

Note that while the original API requires this to be called, this module does NOT rely in any way on this method. In particular, a client is fully functional and begins to receive messages as soon as the IvyStart() method is called.

ivy.std_api.IvySendDieMsg(client: IvyClient) → None

Sends a “die” message to client, instructing him to terminate.

Parameters:

client – an ivy.ivy.IvyClient object, as returned by IvyGetApplication()

ivy.std_api.IvySendDirectMsg(client: IvyClient, num_id: int, msg: str) → None

Sends a direct message to an other Ivy client, with the supplied numerical id and message.

Parameters:

  • client: an ivy.ivy.IvyClient object, as returned by IvyGetApplication()

  • num_id: an additional integer to use. It may, or may not, be meaningful, this only depends on the usage your application makes of it, the Ivy protocol itself does not care and simply transmits it along with the message.

  • msg: the message to send

ivy.std_api.IvySendError(client: IvyClient, num_id: int, error_msg: str) → None

Sends an “error” message to client

Parameters:

  • client: an ivy.ivy.IvyClient object, as returned by IvyGetApplication()

  • num_id: an additional integer to use. It may, or may not, be meaningful, this only depends on the usage your application makes of it, the Ivy protocol itself does not care and simply transmits it along with the message.

  • error_msg: the message to send

ivy.std_api.IvySendMsg(msg: str) → int

Sends a message on the bus, to the agents which have one or more bindings that the message matches.

ivy.std_api.IvySendPing(client: IvyClient) → None

Sends a PING message to the client. See also: IvyBindPong()

ivy.std_api.IvySetPongCallback(on_pong_fct: Callable) → None

alias for IvyBindPong() (IvySetPongCallback is the name used in ivy-c)

ivy.std_api.IvyStart(ivybus: str | None = None) → None

Starts the Ivy server and fully activates the client. Please refer to the discussion in IvyMainLoop() ‘s documentation.

ivy.std_api.IvyStop() → None

Notifies the other participants on the bus that this agent is signing off, and properly terminates the underlying listening thread. When this method returns, the agent is disconnected from the bus.

ivy.std_api.IvyTimerModify(timer_id: int, delay_ms: int) → None

Modifies a timer’s delay. Note that the modification will happen after the next tick.

Parameters:

  • timer_id: id of the timer to modify, as returned by IvyTimerRepeatAfter()

  • delay: the delay, in milliseconds, between ticks

ivy.std_api.IvyTimerRemove(timer_id: int) → None

Stops and removes a given timer.

Parameters:

timer_id – id of the timer, as returned by IvyTimerRepeatAfter()

ivy.std_api.IvyTimerRepeatAfter(count: int, delay_ms: int, callback: Callable) → int

Creates and activates a new timer

Parameters:

  • count: nb of time to repeat the loop, 0 (zero) for an endless loop

  • delay_ms: the delay between ticks, in milliseconds

  • callback: the function to call on every tick. That function is called without any parameters.

Returns:

the timer’s id

ivy.std_api.IvyUnBindMsg(binding_id: int) → str

Unregisters a binding. This is the same as IvyUnbindMsg(), except that it is named like in the Java API (unBindMsg()). If in doubt, use IvyUnbindMsg() preferably.

Parameters:

binding_id – the binding’s id, as previously returned by IvyBindMsg()

Returns:

the regexp corresponding to the unsubscribed binding

Raises:

KeyError – if no such subscription can be found

ivy.std_api.IvyUnbindMsg(binding_id: int) → str

Unregisters a binding.

Parameters:

binding_id – the binding’s id, as previously returned by IvyBindMsg()

Returns:

the regexp corresponding to the unsubscribed binding

Raises:

KeyError – if no such subscription can be found

New in version 3.2.

ivy.std_api.void_function(*arg: Any, **kw: Any) → Any

A function that accepts any number of parameters and does nothing