Struct taskchampion::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 Task and TaskMut types. Use of two types for tasks allows easy read-only manipulation of lots of tasks, with exclusive access required only for modifications.

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 is “renumbered” during the garbage-collection process.

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>,

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.

This is a low-level method, and requires knowledge of the Task data model. Prefer to use the [TaskMut] methods to modify tasks, where possible.

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_uuids(&mut self) -> Result<Vec<Uuid>, Error>

Get the UUIDs of all tasks

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<Rc<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.

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

Get an existing task by its UUID

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

Create a new task.

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

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

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_ops(&mut self) -> Result<Vec<ReplicaOp>, Error>

Return undo local operations until the most recent UndoPoint, returning an empty Vec if there are no local operations to undo.

pub fn commit_undo_ops( &mut self, undo_ops: Vec<ReplicaOp> ) -> Result<bool, Error>

Undo local operations in storage, returning a boolean indicating success.

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>

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).