Expand description
Blocking, single-object distributed data structures.
Each Map or Log is stored as one JSON object. Every public operation
is synchronous and may block the calling thread on object-store I/O. Reads
download and decode the complete structure. Mutations additionally encode
and conditionally replace the complete structure, so their CPU, memory, and
transfer costs are O(n) in the total structure size, not merely the item
being accessed. Applications must bound structure growth accordingly.
A read operation observes one coherent object version (a snapshot), but a
sequence of calls is not a transaction. Mutations use compare-and-swap. A
concurrent writer can therefore produce Error::Conflict; this crate does
not retry automatically because retry policy, backoff, and idempotency belong
to the caller.
§Bounded conflict retries
A retry must re-run the complete operation so it reads a fresh snapshot. Keep attempts bounded and inspect the final conflict:
use objsds::{Error, Map, Version};
use objsds_store::ObjectStore;
use serde::{Serialize, de::DeserializeOwned};
fn insert_with_limit<S, V>(
map: &Map<S, V>,
key: &str,
value: V,
max_attempts: usize,
) -> Result<Version, Error<S::Error>>
where
S: ObjectStore,
V: Clone + Serialize + DeserializeOwned,
{
assert!(max_attempts > 0);
let mut last_conflict = None;
for _ in 0..max_attempts {
match map.insert(key, value.clone()) {
Ok(version) => return Ok(version),
Err(Error::Conflict(conflict)) => last_conflict = Some(conflict),
Err(error) => return Err(error),
}
// Apply bounded backoff or jitter here if appropriate.
}
Err(Error::Conflict(
last_conflict.expect("at least one attempt was made"),
))
}observed: Some(version) means another object version was present when the
failed condition was inspected; None means the object was absent then.
Either observation can already be stale, so use it for diagnostics rather
than as a new expected version.
Re-exports§
pub use objsds_store_s3 as s3;
Structs§
- Already
Exists Error - Creation found an object already present at the requested location.
- Conflict
Error - A conditional replacement did not observe the expected object version.
- Log
- A single-object append-only JSON log.
- LogBuilder
- Builder for one append-only JSON Log.
- LogId
- Opaque, sortable identifier for a log record.
- Map
- A single-object UTF-8/JSON map.
- MapBuilder
- Builder for one UTF-8/JSON Map.
- Objsds
- Client sharing one object store and namespace.
- Objsds
Builder - Builder for
Objsds. - Record
- One immutable Log record.
- Store
Error - The object store could not complete an operation.
- Version
- An opaque object version supplied by a store.
Enums§
- Build
Error - Invalid client or structure configuration.
- Compatibility
Error - Persisted metadata is incompatible with the requested structure.
- Document
Error - A document could not be encoded or decoded.
- Error
- An
objsdsoperation error. - Insert
IfAbsent - Result of
Map::insert_if_absent.