Module spin_sdk.wit.imports.atomics

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.

Global variables

var CasError

The error returned by a CAS operation

Functions

def increment(bucket: Bucket,
key: str,
delta: int) ‑> int

Expand source code

def increment(bucket: wasi_keyvalue_store.Bucket, key: str, delta: int) -> int:
    """
    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)`.
    
    Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.wasi_keyvalue_store.Error)`
    """
    raise NotImplementedError

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

Raises: Err(Error)

def swap(cas: Cas,
value: bytes) ‑> None

Expand source code

def swap(cas: Cas, value: bytes) -> None:
    """
    Perform the swap on a CAS operation. This consumes the CAS handle and returns an error if
    the CAS operation failed.
    
    Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.atomics.CasError)`
    """
    raise NotImplementedError

Perform the swap on a CAS operation. This consumes the CAS handle and returns an error if the CAS operation failed.

Raises: Err(CasError)

Classes

class Cas

Expand source code

class Cas:
    """
    A handle to a CAS (compare-and-swap) operation.
    """
    
    @classmethod
    def new(cls, bucket: wasi_keyvalue_store.Bucket, key: str) -> Self:
        """
        Construct a new CAS operation. Implementors can map the underlying functionality
        (transactions, versions, etc) as desired.
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.wasi_keyvalue_store.Error)`
        """
        raise NotImplementedError
    def current(self) -> Optional[bytes]:
        """
        Get the current value of the key (if it exists). This allows for avoiding reads if all
        that is needed to ensure the atomicity of the operation
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.wasi_keyvalue_store.Error)`
        """
        raise NotImplementedError
    def __enter__(self) -> Self:
        """Returns self"""
        return self
                                
    def __exit__(self, exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None) -> bool | None:
        """
        Release this resource.
        """
        raise NotImplementedError

A handle to a CAS (compare-and-swap) operation.

Static methods

def new(bucket: Bucket,
key: str) ‑> Self

Construct a new CAS operation. Implementors can map the underlying functionality (transactions, versions, etc) as desired.

Raises: Err(Error)

Methods

def current(self) ‑> bytes | None

Expand source code

def current(self) -> Optional[bytes]:
    """
    Get the current value of the key (if it exists). This allows for avoiding reads if all
    that is needed to ensure the atomicity of the operation
    
    Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.wasi_keyvalue_store.Error)`
    """
    raise NotImplementedError

Get the current value of the key (if it exists). This allows for avoiding reads if all that is needed to ensure the atomicity of the operation

Raises: Err(Error)

class CasError_CasFailed (value: Cas)

Expand source code

@dataclass
class CasError_CasFailed:
    value: Cas

CasError_CasFailed(value: spin_sdk.wit.imports.atomics.Cas)

Instance variables

var value : Cas

class CasError_StoreError (value: Error_NoSuchStore | Error_AccessDenied | Error_Other)

Expand source code

@dataclass
class CasError_StoreError:
    value: wasi_keyvalue_store.Error

CasError_StoreError(value: Union[spin_sdk.wit.imports.wasi_keyvalue_store.Error_NoSuchStore, spin_sdk.wit.imports.wasi_keyvalue_store.Error_AccessDenied, spin_sdk.wit.imports.wasi_keyvalue_store.Error_Other])

Instance variables

var value : Error_NoSuchStore | Error_AccessDenied | Error_Other