atomic.wit

/// A keyvalue interface that provides atomic operations.
/// 
/// Atomic operations are single, indivisible operations. When a fault causes an atomic operation to
/// fail, it will appear to the invoker of the atomic operation that the action either completed
/// successfully or did nothing at all.
/// 
/// Please note that this interface is bare functions that take a reference to a bucket. This is to
/// get around the current lack of a way to "extend" a resource with additional methods inside of
/// wit. Future version of the interface will instead extend these methods on the base `bucket`
/// resource.
interface atomics {
  	use store.{bucket, error};

	/// The error returned by a CAS operation
	variant cas-error {
		/// A store error occurred when performing the operation
		store-error(error),
		/// The CAS operation failed because the value was too old. This returns a new CAS handle
		/// for easy retries, as well as the current value for comparison. Implementors MUST return a CAS handle that has been updated to the
		/// latest version or transaction.
		cas-failed(tuple<cas,option<list<u8>>>),
	}

	/// A handle to a CAS (compare-and-swap) operation.
	resource cas {
		/// Construct a new CAS handle for `key`.
		///
		/// This handle should guarantee that a subsequent `swap` operation will operate on data that has
		/// not been modified since this call. If that condition is not met, `swap` should return `error`.
		///
		/// Note that this handle does not necessarily guarantee that no other operations occur on the key
		/// after the handle is created, only that `error` is returned when calling `swap` if other operations did occur.
		new: static func(bucket: borrow<bucket>, key: string) -> result<cas, error>;

		/// Construct a new CAS handle returning the current value of `key`.
		///
		/// This handle should guarantee that a subsequent `swap` operation will operate on data that has
		/// not been modified since this call. If that condition is not met, `swap` should return `error`.
		///
		/// Note that this handle does not necessarily guarantee that no other operations occur on the key
		/// after the handle is created, only that `error` is returned when calling `swap` if other operations did occur.
		new-with-read: static func(bucket: borrow<bucket>, key: string) -> result<tuple<cas, option<list<u8>>>, error>;
	}

  	/// Atomically increment the value associated with the key in the store by the given delta. It
	/// returns the new value.
	///
	/// If the key does not exist in the store, it creates a new key-value pair with the value set
	/// to the given delta. 
	///
	/// If any other error occurs, it returns an `Err(error)`.
	increment: func(bucket: borrow<bucket>, key: string, delta: s64) -> result<s64, error>;

	/// Perform the swap on a CAS operation. This consumes the CAS handle and returns an error if
	/// the CAS operation failed.
	swap: func(cas: cas, value: list<u8>) -> result<_, cas-error>;
}