Struct Replica

pub struct Replica { /* private fields */ }

A replica represents an instance of a user’s task data, providing an easy interface for querying and modifying that data.

Tasks

Tasks are uniquely identified by UUIDs. Most task modifications are performed via the TaskData or Task types. The first is a lower-level type that wraps the key-value store representing a task, while the second is a higher-level type that supports methods to update specific properties, maintain dependencies and tags, and so on.

Operations

Changes to a replica occur by committing Operationss. All methods that change a replica take an argument of type &mut Operations, and the necessary operations are added to that sequence. Those changes may be reflected locally, such as in a Task or TaskData value, but are not reflected in the Replica’s storage until committed with Replica::commit_operations.

Undo is supported by producing an Operations value representing the operations to be undone. These are then committed with Replica::commit_reversed_operations.

Working Set

A replica maintains a “working set” of tasks that are of current concern to the user, specifically pending tasks. These are indexed with small, easy-to-type integers. Newly pending tasks are automatically added to the working set, and the working set can be “renumbered” when necessary.

Implementations

impl Replica

pub fn new(storage: Box<dyn Storage>) -> Replica

pub fn update_task<S1, S2>( &mut self, uuid: Uuid, property: S1, value: Option<S2>, ) -> Result<TaskMap, Error>

where S1: Into<String>, S2: Into<String>,

👎Deprecated since 0.7.0: please use TaskData instead

Update an existing task. If the value is Some, the property is added or updated. If the value is None, the property is deleted. It is not an error to delete a nonexistent property.

pub fn all_tasks(&mut self) -> Result<HashMap<Uuid, Task>, Error>

Get all tasks represented as a map keyed by UUID

pub fn all_task_data(&mut self) -> Result<HashMap<Uuid, TaskData>, Error>

Get all task represented as a map of TaskData keyed by UUID

pub fn all_task_uuids(&mut self) -> Result<Vec<Uuid>, Error>

Get the UUIDs of all tasks

pub fn pending_tasks(&mut self) -> Result<Vec<Task>, Error>

Get an array containing all pending tasks

pub fn pending_task_data(&mut self) -> Result<Vec<TaskData>, Error>

pub fn working_set(&mut self) -> Result<WorkingSet, Error>

Get the “working set” for this replica. This is a snapshot of the current state, and it is up to the caller to decide how long to store this value.

pub fn dependency_map( &mut self, force: bool, ) -> Result<Arc<DependencyMap>, Error>

Get the dependency map for all pending tasks.

A task dependency is recognized when a task in the working set depends on a task with status equal to Pending.

The data in this map is cached when it is first requested and may not contain modifications made locally in this Replica instance. The result is reference-counted and may outlive the Replica.

If force is true, then the result is re-calculated from the current state of the replica, although previously-returned dependency maps are not updated.

Calculating this value requires a scan of the full working set and may not be performant. The TaskData API avoids generating this value.

pub fn get_task(&mut self, uuid: Uuid) -> Result<Option<Task>, Error>

Get an existing task by its UUID

pub fn get_task_data(&mut self, uuid: Uuid) -> Result<Option<TaskData>, Error>

Get an existing task by its UUID, as a TaskData.

pub fn get_task_operations(&mut self, uuid: Uuid) -> Result<Operations, Error>

Get the operations that led to the given task.

This set of operations is suitable for providing an overview of the task history, but does not satisfy any invariants around operations and task state. That is, it is not guaranteed that the returned operations, if applied in order, would generate the current task state.

It is also not guaranteed to be the same on every replica. Differences can occur when conflicting operations were performed on different replicas. The “losing” operations in those conflicts may not appear on all replicas. In practice, conflicts are rare and the results of this function will be the same on all replicas for most tasks.

pub fn new_task( &mut self, status: Status, description: String, ) -> Result<Task, Error>

👎Deprecated since 0.7.0: please use create_task and call Task methods set_status, set_description, and set_entry

Create a new task, setting modified, description, status, and entry.

This uses the high-level task interface. To create a task with the low-level interface, use TaskData::create.

pub fn create_task( &mut self, uuid: Uuid, ops: &mut Operations, ) -> Result<Task, Error>

Create a new task.

Use [’Uuid::new_v4`] to invent a new task ID, if necessary. If the task already exists, it is returned.

pub fn import_task_with_uuid(&mut self, uuid: Uuid) -> Result<Task, Error>

👎Deprecated since 0.7.0: please use TaskData instead

Create a new, empty task with the given UUID. This is useful for importing tasks, but otherwise should be avoided in favor of create_task. If the task already exists, this does nothing and returns the existing task.

pub fn delete_task(&mut self, uuid: Uuid) -> Result<(), Error>

👎Deprecated since 0.7.0: please use TaskData::delete

Delete a task. The task must exist. Note that this is different from setting status to Deleted; this is the final purge of the task.

Deletion may interact poorly with modifications to the same task on other replicas. For example, if a task is deleted on replica 1 and its description modified on replica 1, then after both replicas have fully synced, the resulting task will only have a description property.

pub fn commit_operations(&mut self, operations: Operations) -> Result<(), Error>

Commit a set of operations to the replica.

All local state on the replica will be updated accordingly, including the working set and and temporarily cached data.

pub fn sync( &mut self, server: &mut Box<dyn Server>, avoid_snapshots: bool, ) -> Result<(), Error>

Synchronize this replica against the given server. The working set is rebuilt after this occurs, but without renumbering, so any newly-pending tasks should appear in the working set.

If avoid_snapshots is true, the sync operations produces a snapshot only when the server indicate it is urgent (snapshot urgency “high”). This allows time for other replicas to create a snapshot before this one does.

Set this to true on systems more constrained in CPU, memory, or bandwidth than a typical desktop system

pub fn get_undo_operations(&mut self) -> Result<Operations, Error>

Return the operations back to and including the last undo point, or since the last sync if no undo point is found.

The operations are returned in the order they were applied. Use Replica::commit_reversed_operations to “undo” them.

pub fn commit_reversed_operations( &mut self, operations: Operations, ) -> Result<bool, Error>

Commit the reverse of the given operations, beginning with the last operation in the given operations and proceeding to the first.

This method only supports reversing operations if they precisely match local operations that have not yet been synchronized, and will return false if this is not the case.

pub fn rebuild_working_set(&mut self, renumber: bool) -> Result<(), Error>

Rebuild this replica’s working set, based on whether tasks are pending or not. If renumber is true, then existing tasks may be moved to new working-set indices; in any case, on completion all pending and recurring tasks are in the working set and all tasks with other statuses are not.

pub fn expire_tasks(&mut self) -> Result<(), Error>

Expire old, deleted tasks.

Expiration entails removal of tasks from the replica. Any modifications that occur after the deletion (such as operations synchronized from other replicas) will do nothing.

Tasks are eligible for expiration when they have status Deleted and have not been modified for 180 days (about six months). Note that completed tasks are not eligible.

pub fn add_undo_point(&mut self, force: bool) -> Result<(), Error>

👎Deprecated since 0.7.0: Push an Operation::UndoPoint onto your Operations instead.

Add an UndoPoint, if one has not already been added by this Replica. This occurs automatically when a change is made. The force flag allows forcing a new UndoPoint even if one has already been created by this Replica, and may be useful when a Replica instance is held for a long time and used to apply more than one user-visible change.

pub fn num_local_operations(&mut self) -> Result<usize, Error>

Get the number of operations local to this replica and not yet synchronized to the server.

pub fn num_undo_points(&mut self) -> Result<usize, Error>

Get the number of undo points available (number of times undo will succeed).