space_ex

v0.8.0

space_ex v0.8.0 SpaceEx.Event

Allows for the server to notify us only when a conditional expression becomes true.

Events are an efficient way to wait for a particular condition or state. This could be e.g. waiting for a vessel to reach a given altitude, waiting for a certain time, waiting for a burn to be nearly complete, etc.

To set up an event, you will need to create a SpaceEx.KRPC.Expression that returns a boolean value. Generally, this is done by issuing one or more “call” expressions (to retrieve useful data), and comparing them with one or more “constant” expressions, using comparison expressions like “equals”, “greater than”, etc. Complex logic chains may be created with boolean expressions like “and”, “or”, etc.

Events are really just streams that receive their first (and only) update once the condition becomes true. As such, they cannot currently be reused; once an event becomes true, subsequent attempts to wait on the same event will always return immediately, even if the conditional expression is no longer true.

Link to this section Summary

Functions

create(expression, opts \\ [])

Creates an event from an expression

remove(event)

Detach from an event, and shut down the underlying stream if possible

set_rate(event, rate)

Set the polling rate of an event

start(event)

Start a previously created event

subscribe(event, opts \\ [])

Receive a message when an event triggers (becomes true)

wait(event, opts \\ [])

Waits for an event to trigger (become true)

Link to this section Functions

Link to this function create(expression, opts \\ [])

Creates an event from an expression.

expression should be a SpaceEx.KRPC.Expression reference. The expression must return a boolean type.

Options

  • :start — whether the event stream should be started immediately. If false, you can prepare an event before it becomes needed later. Default: true
  • :rate — how often the server checks the condition, per second. Default: 0 (unlimited.
Link to this function remove(event)

Detach from an event, and shut down the underlying stream if possible.

See SpaceEx.Stream.remove/1.

Link to this function set_rate(event, rate)

Set the polling rate of an event.

See SpaceEx.Stream.set_rate/2.

Link to this function start(event)

Start a previously created event.

See SpaceEx.Stream.start/1.

Link to this function subscribe(event, opts \\ [])

Receive a message when an event triggers (becomes true).

This is the non-blocking version of wait/2. Once the event is complete, a message will be delivered to the calling process. By default, this will also call Event.remove/1 to clean up the event stream.

Because events are effectively just streams, this message will be in the form of {:stream_result, id, value} where id is the value of event.id.

This function behaves identically to SpaceEx.Stream.subscribe/2, except that the immediate and remove options are both true by default. It’s unlikely that you’ll want to change either of these, since event streams only ever get a single message.

Link to this function wait(event, opts \\ [])

Waits for an event to trigger (become true).

This will wait until the server reports that the conditional expression has become true. It will block for up to opts[:timeout] milliseconds (default: forever, aka :infinity), after which it will throw an exit signal.

You can technically catch this exit signal with try ... catch :exit, _, but it’s not generally considered good practice to do so. As such, wait/2 timeouts should generally be reserved for “something has gone badly wrong”.

If this function is called and returns (i.e. does not time out), then the event is complete. As long as the stream remains alive, future calls will immediately return true as well, even if the condition is no longer true.

Since events are single-use, by default, this will call Event.remove/1 before returning. This will allow the underlying stream to unregister itself from the server. You may suppress this behaviour with the remove: true option.