pub struct Zero<C = ()> { /* private fields */ }Expand description
A Zero client: syncs the rows of named queries from zero-cache into a local replica, keeps materialized views of them current, and runs mutators optimistically before the server confirms them.
C is what mutators are given besides their arguments, such as the
logged-in user’s auth data. Everything runs on the thread that made the
client, driven by the Scheduler and the socket events.
Implementations§
Source§impl<C: 'static> Zero<C>
impl<C: 'static> Zero<C>
Sourcepub fn new(
schema: Arc<Schema>,
context: C,
mutators: Vec<Mutator<C>>,
options: ZeroOptions,
scheduler: Rc<dyn Scheduler>,
socket_factory: Option<Rc<dyn SocketFactory>>,
) -> Result<Self, Error>
pub fn new( schema: Arc<Schema>, context: C, mutators: Vec<Mutator<C>>, options: ZeroOptions, scheduler: Rc<dyn Scheduler>, socket_factory: Option<Rc<dyn SocketFactory>>, ) -> Result<Self, Error>
schema: the app’s schema.mutators: every mutator the client may run. Pending mutations are replayed by name, so each must be registered.scheduler: the clock and timers, on the app’s event loop; tests pass aManualScheduler.socket_factory: opens the sync socket. Without one the client runs locally.
When the server no longer has the client’s state, such as after it
closed the connection for a message over its size limit, and the
app set no on_client_state_not_found, the client replaces itself
by a new one on the same store, as JS reloads the page: a new client
ID and client group, the views and preloads kept, and pending
mutations of the old client group dropped.
Sourcepub fn client_group_id(&self) -> String
pub fn client_group_id(&self) -> String
The client group’s ID, which changes when the client replaces itself.
Sourcepub fn connection(&self) -> &Connection
pub fn connection(&self) -> &Connection
The client’s connection to zero-cache.
Sourcepub fn materialize(
&self,
query: &(impl ZeroQuery<C> + ?Sized),
ttl: &Ttl,
) -> Result<MaterializedView, Error>
pub fn materialize( &self, query: &(impl ZeroQuery<C> + ?Sized), ttl: &Ttl, ) -> Result<MaterializedView, Error>
A view of the query’s rows that stays current. Named queries are synced from the server; an unnamed one only sees local data.
Sourcepub fn live<Q>(&self, query: &Q, ttl: &Ttl) -> Result<LiveView<Q::Value>, Error>
pub fn live<Q>(&self, query: &Q, ttl: &Ttl) -> Result<LiveView<Q::Value>, Error>
The query’s result read as its Rust type and kept current: its rows,
the row of a one() query, or the value of an aggregate, from a
typed Query or a named query’s
QueryRequest. Fails when the query can’t be materialized, or when
its rows don’t read as the type (an Error::Message saying why).
Sourcepub fn run(
&self,
query: &(impl ZeroQuery<C> + ?Sized),
run_type: RunType,
ttl: Option<&Ttl>,
) -> Deferred<ViewValue> ⓘ
pub fn run( &self, query: &(impl ZeroQuery<C> + ?Sized), run_type: RunType, ttl: Option<&Ttl>, ) -> Deferred<ViewValue> ⓘ
The query’s rows: what the replica holds now (Unknown), or once
the server has confirmed them on this connection (Complete) or
any (Cached). Await the result, or read it once settled.
An unnamed query only sees local data: the server never confirms
it, so waiting for Complete or Cached never settles.
Sourcepub fn preload(
&self,
query: &(impl ZeroQuery<C> + ?Sized),
ttl: &Ttl,
) -> Preload
pub fn preload( &self, query: &(impl ZeroQuery<C> + ?Sized), ttl: &Ttl, ) -> Preload
Keeps the query’s rows synced without a view, until cleanup.
Preloading an unnamed query does nothing. JS’s default ttl for a
preload is Ttl::DEFAULT_PRELOAD, not Ttl::default().
Sourcepub fn inspector(&self) -> Inspector<C>
pub fn inspector(&self) -> Inspector<C>
The inspector (zero.inspector): the client’s queries and metrics
and what zero-cache knows of them, for debugging and tooling.
Sourcepub fn mutate(&self, name: &str, args: Option<Value>) -> MutatorResult
pub fn mutate(&self, name: &str, args: Option<Value>) -> MutatorResult
Runs a mutator on the client now and sends it to the server. A
mutator not registered with this client doesn’t run: both outcomes
are a ZeroError saying so. JS throws that error instead.
Sourcepub fn mutate_request(&self, request: MutateRequest) -> MutatorResult
pub fn mutate_request(&self, request: MutateRequest) -> MutatorResult
mutate of a request, such as a define_mutator
definition applied to its arguments: JS’s and Swift’s
zero.mutate(request).
Sourcepub fn add_mutation_outcome_listener(
&self,
listener: impl Fn(&MutationServerOutcome) + 'static,
) -> Box<dyn Fn()>
pub fn add_mutation_outcome_listener( &self, listener: impl Fn(&MutationServerOutcome) + 'static, ) -> Box<dyn Fn()>
Calls listener with the server’s outcome of each mutation this
client makes, once per mutation, as the server reports it. Returns
the function that removes it.
Unlike a mutation’s server result, it hears the outcome of a
mutation sent again after the connection came back: server settles
with MutationOutcome::ZeroError
when the client gives up connecting
(disconnect_timeout_ms), and
the mutation is replayed when it reconnects. A mutation still pending
when the app quits is replayed when it next launches, but its outcome
isn’t reported, nor is a pending mutation’s when the client replaces
itself. The listeners stay with the client when it does.
Use it for a single place that shows rejections, instead of each
server result, so a rejection isn’t shown twice. To read the
outcomes elsewhere, such as from an async task, send them to a
channel from the listener. Swift’s addMutationOutcomeListener: the
JS client has no counterpart.
Sourcepub fn set_visible(&self, visible: bool)
pub fn set_visible(&self, visible: bool)
The app was shown, or hidden. Hidden for
ZeroOptions::hidden_disconnect_delay_ms, the client disconnects
until it is shown again.
Sourcepub fn reconnect_now(&self)
pub fn reconnect_now(&self)
The network may be back: reconnect without waiting for the backoff.
Sourcepub fn when_pending_settled(&self, done: impl FnOnce() + 'static)
pub fn when_pending_settled(&self, done: impl FnOnce() + 'static)
Calls done once the server has confirmed every pending mutation,
or when it can’t.
Sourcepub fn close(&self)
pub fn close(&self)
Closes the connection. Pending mutations and queries fail, and views stop updating.
Sourcepub fn flush_storage(&self)
pub fn flush_storage(&self)
Waits for the local store’s queued writes, such as before the app
exits. A failure to write them is reported to
ZeroOptions::on_storage_failure.
Sourcepub fn delete(&self) -> DroppedDatabases
pub fn delete(&self) -> DroppedDatabases
Closes the client and deletes its local data (zero.delete()): the
replica and pending mutations of this user and storage key, under
every schema version. Pending mutations the server hasn’t confirmed
are lost. Use it to log a user out.