mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2024-11-19 18:11:28 +01:00
Code Issues Projects Releases Wiki Activity
d60077a8d9
core-lightning/doc/lightning-wait.7.md
Rusty Russell c2eadb88be wait: new command to wait on indexes. 
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.
2023-07-23 13:48:37 +09:30

2.3 KiB
Raw Blame History

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