Project: /_project.yaml Book: /_book.yaml
Defined in fuchsia.ledger/ledger.fidl
Base interface for all services offered by the Ledger.
In case of an unexpected error on one of the service offered by the Ledger, the service will close the connected channel, sending a zx.status
as an epitaph.
If a client needs to ensure a sequence of operation has been processed by the service, it can issue a Sync
command. The response will be send once all request started before the Sync
request has been processed by the service.
Defined in fuchsia.ledger/ledger.fidl
Retrieves the page with the given identifier, creating it if needed, and binds page_request
to it. A null
identifier can be passed to create a new page with a random unique identifier. It is allowed to connect to the same page concurrently multiple times.
Parameters: id
the identifier of the page, or null
to create a new page with a random identifier.
Gets the page with identifier [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]. This is a convenience method equivalent to: GetPage([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], page_request).
Sets the ConflictResolverFactory
to use for resolving conflicts on pages. If this method has never been called, a last-one-wins policy will be used for every page. If this method is called multiple times, the factories are kept and conflict resolver requests are sent to one of the connected factories. If all factories are later disconnected, pages that already have a conflict resolution strategy (because they were opened before the factory disconnected) will continue using their current strategy. The pages for which no conflict resolution is set up will not get their conflicts resolved until this method is called again.
Defined in fuchsia.ledger/ledger.fidl
A page is the smallest unit of syncable data.
Returns the identifier for the page.
Creates a snapshot of the page, allowing the client app to read a consistent view of the content of the page. If key_prefix
is provided, the resulting snapshot includes only the entries with matching keys.
If watcher
is provided, it will receive notifications for changes of the page state on this page connection newer than the resulting snapshot. Change notifications will only contain the entries matching key_prefix
. To receive all changes, use an empty key_prefix
.
Mutations are bundled together into atomic commits. If a transaction is in progress, the list of mutations bundled together is tied to the current transaction. If no transaction is in progress, mutations will be bundled with the following rules:
GetSnapshot()
or StartTransaction()
will commit any pending mutations.Put()
and PutWithPriority()
can be used for small values that fit inside a FIDL message. If the value is bigger, a reference must be first created using CreateReferenceFromSocket()
or CreateReferenceFromBuffer()
and then PutReference()
can be used. PutWithPriority()
and PutReference()
have an additional priority
parameter managing the synchronization policy for this value. Put()
uses a default priority of Priority.EAGER
. For the list of available priorities and their definition, see Priority
.Deletes all entries in the page. Outside of a transaction, this operation is equivalent to deleting every key currently present on the page in a single transaction. In a transaction, this operation is equivalent to deleting every key present in the page before the transaction, as well as any new key added since the transaction started.
Creates a new reference. The object is not part of any commit. It must be associated with a key using PutReference()
. The content of the reference will be the content of the socket. The content size must be equal to size
, otherwise the call will fail.
Creates a new reference. The object is not part of any commit. It must be associated with a key using PutReference()
. The content of the reference will be the content of the buffer.
Transactions allow the client to ensures changes are seen atomically by observers of this page. Once a transaction is started with StartTransaction()
, every call to Put(...)
and Delete(...)
will not be visible until either Commit()
is called, and all changes are applied in a single commit, or Rollback()
is called and all changes are discarded.
Parallel transactions on the same page connection are not allowed, and calling StartTransaction()
when a transaction is already in progress returns an error. However, a client is free to connect to the same page multiple times, and run parallel transactions on the same page using separate connections. In this case, committing each transaction creates divergent commits, which are later subject to conflict resolution.
When a transaction is in progress, the page content visible on this page connection is pinned to the state from when StartTransaction()
was called. In particular, no watch notifications are delivered, and the conflict resolution is not invoked while the transaction is in progress. If conflicting changes are made or synced while the transaction is in progress, conflict resolution is invoked after the transaction is committed.
Starting a transaction will block until all watchers registered on this page connection have received the current page state, ie. the one that will be used as the base of the transaction. Put (with all its variants) and Delete calls may be pipelined while StartTransaction() is pending and will be taken into account in the transaction while it is pending.
Sets a watcher to track the synchronisation state of this page. The current state is immediately sent to the watcher when this method is called.
Waits until all conflicts are resolved before calling the callback. The client can call this method multiple times, even before the previous calls are completed. Callbacks will be executed in the order they were added and indicate whether a merge happened between the callback registration and its execution. If there are no pending conflicts at the time this is called, the callback gets executed right away.
Defined in fuchsia.ledger/ledger.fidl
The content of a page at a given time. Closing the connection to a Page
interface closes all PageSnapshot
interfaces it created. The contents provided by this interface are limited to the prefix provided to the Page.GetSnapshot() call.
Returns the entries in the page with keys greater or equal to key_start
using the lexicographic order. If key_start
is empty, all entries are returned. If the result fits in a single fidl message, next_token
will be equal to NULL. Otherwise, next_token
will have a non-NULL value. To retrieve the remaining results, another call to GetEntries
should be made, initializing the optional token
argument with the value of next_token
returned in the previous call. next_token
will not be NULL as long as there are more results and NULL once finished. Only EAGER
values are guaranteed to be returned inside entries
. Missing LAZY
values can be retrieved over the network using Fetch(). The returned entries
are sorted by key
.
Same as GetEntries()
. The connection will be closed with a ZX_ERR_BAD_STATE
epitaph if a value does not fit in a FIDL message.
Returns the keys of all entries in the page which are greater or equal to key_start
using the lexicographic order. If key_start
is empty, all keys are returned. The returned keys
are sorted. If the result fits in a single fidl message, next_token
will be equal to NULL. Otherwise, next_token
will have a non-NULL value. To retrieve the remaining results, another call to GetKeys
should be made, initializing the optional token
argument with the value of next_token
returned in the previous call. next_token
will not be NULL as long as there are more results and NULL once finished.
Returns the value of a given key. Only EAGER
values are guaranteed to be returned. Calls when the value is LAZY
and not available will return a NEEDS_FETCH
status. The value can be retrieved over the network using a Fetch() call.
Returns the value of a given key if it fits in a FIDL message. The connection will be closed with a ZX_ERR_BAD_STATE
epitaph if the value does not fit in a FIDL message. See Get()
for additional information.
Fetches the value of a given key, over the network if not already present locally. NETWORK_ERROR
is returned if the download fails (e.g.: network is not available).
Fetches the value of a given key, over the network if not already present locally, and returns a shared handle of a part of the value of a given key, starting at the position that is specified by offset
. If offset
is less than 0, starts at -offset
from the end of the value. Returns at most max_size
bytes. If max_size
is less than 0, returns everything.
Defined in fuchsia.ledger/ledger.fidl
Interface to watch changes to a page. The client will receive changes made by itself, as well as other clients or synced from other devices. The contents of a transaction will never be split across multiple OnChange() calls, but the contents of multiple transactions may be merged into one OnChange() call.
Called for changes made on the page. If the result fits in a single fidl message, result_state
will be COMPLETED
. Otherwise, OnChange will be called multiple times and result_state
will be PARTIAL_STARTED
the first time, PARTIAL_CONTINUED
the following ones and finally PARTIAL_COMPLETED
on the last call. No new OnChange() call will be made while the previous one is still active. If clients are interested in the full content of the page at the time of the change, they can request a PageSnapshot in the callback. This request is optional and can be requested in any partial (started, continued or completed) and/or COMPLETED OnChange call. In any case, all requests made on a sequence of OnChange calls for the same page change, will always return the same snapshot: the one including all changes.
Note that calls to Page.StartTransaction() on the page connection on which the watcher was registered will block until all OnChange() calls have finished.
Defined in fuchsia.ledger/ledger.fidl
This interface lets clients control the conflict resolution policy of the ledger. It allows them to either use pre-defined policies, or provide their own implementation. This can be decided on a page-by-page basis.
Returns the conflict resolution policy for the given page.
Returns a ConflictResolver
to use for the given page. This will only be called if GetPolicy
for the same page returned AUTOMATIC_WITH_FALLBACK
or CUSTOM
.
Defined in fuchsia.ledger/ledger.fidl
A merge result provider, obtained from ConflictResolver.Resolve()
. Can be used to retrieve data about the conflict, and provide the merge result. When all changes have been sent, Done()
should be called to mark the end of incoming merge changes.
GetFullDiff
returns the set of all key/value pairs (entries) that have been modified between the common ancestor (see ConflictResolver.Resolve()
) and the left and right branches.
Values of LAZY
keys may not be present on the device. In that case, the corresponding Value objects within DiffEntry will have a NULL value
field. If needed, left
and right
, provided by the ConflictResolver.Resolve()
method can be used by clients to Fetch these values. If a key is not present at all in one of the branches, its corresponding Value object will be NULL.
The first call to get the DiffEntry
s should be done using a NULL token. If the result does not fit in a single fidl message, next_token
will have a non-NULL value, which can be used to retrieve the rest of the results by calling GetFullDiff()
with that token.
GetConflictingDiff
returns the set of all key/value pairs that were modified on both sides to different values, or deleted on one side and modified on the other.
It behaves like GetFullDiff
otherwise.
Once the result of the merge has been computed Merge()
can be called with all changes that resolve this conflict. If the result does not fit in a single fidl message, Merge()
can be called multiple times. If any of the Merge()
calls fails, i.e. status
is not OK
, all following calls will fail with the same error.
If a key/value pair is sent multiple times in one or several Merge()
call, only the last pair is taken into account.
For all keys for which no merged value has been set (either here or through MergeNonConflictingEntries()
below), the left value will be used. It is thus not necessary to send a MergedValue with a LEFT
value source, unless to overwrite a previous MergedValue.
Automatically merges all non conflicting entries (entries that are modified on one side only or identical on both sides). This is equivalent to sending, through Merge()
, a MergedValue with a RIGHT
ValueSource for all non-conflicting keys modified on the right side. Conflicting entries can still be merged using the Merge()
method.
Marks the end of merge changes to resolve this conflict. After Done()
is called MergeResultProvider
interface cannot be used any more.
Defined in fuchsia.ledger/ledger.fidl
Custom conflict resolver. If a ConflictResolverFactory
is registered, and ConflictResolverFactory.GetPolicy()
returns AUTOMATIC_WITH_FALLBACK
or CUSTOM
when called for a given page, the NewConflictResolver
method will be called and will provide a ConflictResolver
. Each time a custom conflict resolution is needed according to the chosen policy, the method ConflictResolver.Resolve()
will be called, and the client will resolve the conflict by returning the final value for all conflicting keys as well as values for any other key that the client wants to change.
Method called when a conflict needs to be resolved. left
and right
contain the snapshots of the two branches and common_version
that of the lowest common ancestor. common_version
can be NULL if this version is no longer available. The result of the merge can be given through the result_provider
, using the left branch as the base of the merge commit, i.e. only key/value pairs that are different from the left version of the page should be sent. result_provider
can also be used to retrieve the set of differences, i.e. conflicting keys, between the two versions.
Defined in fuchsia.ledger/ledger.fidl
Watcher interface to be implemented by clients who wish to follow the synchronization status of their ledger. SyncStateChanged callback must be called for new state change calls to be sent.
generated
generated
generated
generated
generated
generated
Defined in fuchsia.ledger/ledger.fidl
Type of the identifier of a ledger Page.
Defined in fuchsia.ledger/ledger.fidl
A reference to a value.
Defined in fuchsia.ledger/ledger.fidl
A continuation token for paginated requests.
Defined in fuchsia.ledger/ledger.fidl
A pair of key and value.
Defined in fuchsia.ledger/ledger.fidl
A value inlined in a message.
Defined in fuchsia.ledger/ledger.fidl
A pair of key and an inlined value.
Defined in fuchsia.ledger/ledger.fidl
Defined in fuchsia.ledger/ledger.fidl
A change in the page. If source
is set to NEW
, new_value
must be set to the new value. If source
is not NEW
, new_value
and priority
are ignored.
Defined in fuchsia.ledger/ledger.fidl
An entry in a diff, as returned by MergeResultProvider
.
If base
, left
or right
are NULL, this means that the corresponding key was not present in the base, left or right (respectively) branch of the page.
Defined in fuchsia.ledger/ledger.fidl
A value in a DiffEntry.
If the value is LAZY and is not present locally, value
will be NULL. The value can be retrieved using a Fetch()
call on a corresponding snapshot.
Type: uint32
Defined in fuchsia.ledger/ledger.fidl
The result of a wait for conflict resolution. See Page.WaitForConflictResolution
for details.
Type: uint32
Defined in fuchsia.ledger/ledger.fidl
The synchronization priority of a reference.
Type: uint32
Defined in fuchsia.ledger/ledger.fidl
Error returned by the different PageSnapshot methods.
Type: uint32
Defined in fuchsia.ledger/ledger.fidl
Type: uint32
Defined in fuchsia.ledger/ledger.fidl
Strategy to be used when resolving conflicts.
Type: uint32
Defined in fuchsia.ledger/ledger.fidl
Source of the value used to resolve a conflict.
DELETE
deletes the key; NEW
creates a new value; RIGHT
selects the value from the right branch. If no value is sent, the left branch is selected. Used by MergedValue
.
Type: uint32
Defined in fuchsia.ledger/ledger.fidl
Synchronization state.
generated
generated
generated
generated
generated
generated
Defined in fuchsia.ledger/ledger.fidl
A value that is either small enough to be directly embedded in bytes
or that is referenced by reference
.