mirror of
https://github.com/ElementsProject/lightning.git
synced 2025-02-22 22:45:27 +01:00
c2eadb88be
This will initially be for listinvoices, but can be expanded to other list commands. It's documented, but it makes promises which currently don't exist: * listinvoice does not support `index` or `start` yet. * It doesn't actually fire when invoices change yet. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au> Changelog-Added: JSON-RPC: `wait`: new generic command to wait for events.
79 lines
2.3 KiB
Markdown
79 lines
2.3 KiB
Markdown
lightning-wait -- Command to wait for creations, changes and deletions
|
|
======================================================================
|
|
|
|
SYNOPSIS
|
|
--------
|
|
|
|
**wait** *subsystem* *indexname* *nextvalue*
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
|
|
The **wait** RPC command returns once the index given by *indexname*
|
|
in *subsystem* reaches or exceeds *nextvalue*. All indexes start at 0, when no
|
|
events have happened (**wait** with a *nextvalue* of 0 is a way of getting
|
|
the current index, though naturally this is racy!).
|
|
|
|
*indexname* is one of `created`, `updated` or `deleted`:
|
|
- `created` is incremented by one for every new object.
|
|
- `updated` is incremented by one every time an object is changed.
|
|
- `deleted` is incremented by one every time an object is deleted.
|
|
|
|
*subsystem* is one of:
|
|
- `invoices`: corresponding to `listinvoices`.
|
|
|
|
|
|
RELIABILITY
|
|
-----------
|
|
|
|
Indices can go forward by more than one; in particlar, if multiple
|
|
objects were created and the one deleted, you could see this effect.
|
|
Similarly, there are some places (e.g. invoice expiration) where we
|
|
can update multiple entries at once.
|
|
|
|
Indices only monotoncally increase.
|
|
|
|
USAGE
|
|
-----
|
|
|
|
The **wait** RPC is used to track changes in the system. Consider
|
|
tracking invoices being paid or expiring. The simplest (and
|
|
inefficient method) would be:
|
|
|
|
1. Call `listinvoices` to get the current state of all invoices, and
|
|
remember the highest `updated_index`. Say it was 5.
|
|
2. Call `wait invoices updated 6`.
|
|
3. When it returns, call `listinvoices` again to see what changed.
|
|
|
|
This is obviously inefficient, so there are two optimizations:
|
|
|
|
1. Call `listinvoices` with `index=updated` and `start=6` to only see invoices
|
|
with `updated_index` greater than or equal to 6.
|
|
2. `wait` itself may also return some limited subset of fields from the list
|
|
command (it can't do this in all cases); for `invoices` this is `label`
|
|
and `status`, allowing many callers to avoid the `listinvoices` call.
|
|
|
|
RETURN VALUE
|
|
------------
|
|
FIXME
|
|
|
|
On error the returned object will contain `code` and `message` properties,
|
|
with `code` being one of the following:
|
|
|
|
- -32602: If the given parameters are wrong.
|
|
|
|
AUTHOR
|
|
------
|
|
|
|
Rusty Russell <<rusty@rustcorp.com.au>> is mainly
|
|
responsible.
|
|
|
|
SEE ALSO
|
|
--------
|
|
|
|
lightning-listinvoice(7)
|
|
|
|
RESOURCES
|
|
---------
|
|
|
|
Main web site: <https://github.com/ElementsProject/lightning>
|