pub struct Watcher { /* private fields */ }Expand description
The Watcher is the hub where updates are published regarding tables that updated when
observing a connection.
All changes are published to a background thread which then notifies the respective
TableObservers.
§Observing Tables
To be notified of changes, register an observer with Watcher::add_observer.
The Watcher by itself does not automatically watch all tables. The observed tables
are driven by the tables defined by each TableObserver.
A table can be observed by many TableObserver. When the last TableObserver is removed
for a given table, that table stops being tracked.
§Update Propagation
Every time a TableObserver is added or removed, the list of tracked tables is updated and
a counter is bumped. These changes are propagated to State instances when they sync their
state State::sync_tables().
Due to the nature of concurrent operations, it is possible that a connection on different thread will miss the changes applied from adding/removing an observer on the current thread. On the next sync this will be rectified.
If both operation happen on the same thread, everything will work as expected.
§Notifications
To notify the Watcher of changed tables, an instance of either Connection or
State needs to be used. Check each type for more information on how to use
it correctly.
§Remarks
The Watcher currently maintains a list of observed tables that is never pruned. It will
keep growing with every new table that is observed. If you have af fixed set of tables that
you watch on a regular basis this is not an issue. If you have a dynamic list of tables
deleted tables are currently not removed. To be addressed in the future.
Implementations§
Source§impl Watcher
impl Watcher
Sourcepub fn new() -> Result<Arc<Self>, Error>
pub fn new() -> Result<Arc<Self>, Error>
Create a new instance of an in process tracker service.
§Errors
Returns error if the worker thread fails to spawn.
Sourcepub fn add_observer(
&self,
observer: Box<dyn TableObserver>,
) -> Result<TableObserverHandle, Error>
pub fn add_observer( &self, observer: Box<dyn TableObserver>, ) -> Result<TableObserverHandle, Error>
Register a new observer with a list of interested tables.
This function returns a TableObserverHandle which can later be used to
remove the current observer.
§Errors
Returns error if the command which adds the observer to the background thread could not be sent or the handle could not be retrieved.
Sourcepub fn add_observer_with_drop_remove(
self: &Arc<Self>,
observer: Box<dyn TableObserver>,
) -> Result<DropRemoveTableObserverHandle, Error>
pub fn add_observer_with_drop_remove( self: &Arc<Self>, observer: Box<dyn TableObserver>, ) -> Result<DropRemoveTableObserverHandle, Error>
Same as Self::add_observer, but returns a handle that removes the observer
from this Watcher on drop.
§Errors
See Self::add_observer for more details.
Sourcepub fn remove_observer_deferred(
&self,
handle: TableObserverHandle,
) -> Result<(), Error>
pub fn remove_observer_deferred( &self, handle: TableObserverHandle, ) -> Result<(), Error>
Remove an observer via its handle without waiting for the operation to complete.
The removal of observers is deferred to the background thread and will be executed as soon as possible.
If you wish to wait for an observer to finish being removed from the list,
you should use Self::remove_observer()
§Errors
Returns error if the command to remove the observer could not be sent.
Sourcepub fn remove_observer(&self, handle: TableObserverHandle) -> Result<(), Error>
pub fn remove_observer(&self, handle: TableObserverHandle) -> Result<(), Error>
Remove an observer via its handle and wait for it to be removed.
If you wish do not wish to wait for an observer to finish being removed from the list,
you should use Self::remove_observer_deferred()
§Errors
Returns error if the command to remove the observer could not be sent or the reply could not be received.
Sourcepub fn observed_tables(&self) -> Vec<String>
pub fn observed_tables(&self) -> Vec<String>
Return the list of observed tables at this point in time.