api.fabaccess-api/claim.capnp

@0xf8f8864ba0678056;

using CSharp = import "programming_language/csharp.capnp";
$CSharp.namespace("FabAccessAPI.Schema");

using import "/capnp/rpc.capnp".SturdyRef;

using import "persistent.capnp".Persistent;
using import "resource.capnp".Resource;
using import "notify.capnp".Notifiable;
using import "utils.capnp".Fallible;
using import "utils.capnp".OID;
using import "utils.capnp".Map;

interface Claimable {
    claim @0 () -> Fallible(Claim, ClaimError);
    # returns NULL if the resource is *currently* not claimable.
    # drop the returned claim capability to unclaim it.

    interface ClaimError {

    }
}

interface Lockable {
    restore @0 ( sturdy :SturdyRef ) -> ( lock :Lock );
    # Restore a previously saved SturdyRef pointing to a Lock

    lock @1 () -> ( lock :Lock );
    # Take exclusive access to a resource, disowning all other claims on this
    # resource.
    #
    # On resources that do not allow concurrent claims to exist this method
    # behaves similar to `claim`, however it will also succeed if a resource is
    # already claimed, disowning the previous claim.  On resources that do
    # allow concurrent claims this method will disown all current claims on a
    # resource and prevent new claims from being granted until the returned
    # Lock capability is dropped.  A call to `lock` on a resource that is
    # already locked will succeed, invalidating the former lock.
}

interface Claim extends (Notifiable) {
    resource @0 () -> ( resource :Resource );
    # Pointer back to the resource this claim comes from.  Primarily useful when restoring persisted
    # claims or restoring after a connection failure.

    traits @1 () -> Map(OID, AnyPointer);

    disown @2 ();
    # Disown this claim
}

interface Lock extends (Claim) {
    # An exclusive claim on a resource. Only a single Lock may exist for any given resource.

    downgrade @0 () -> ( claim :Claim );
    # Downgrade a lock to a claim, allowing additional claims to be granted on resources that allow
    # for concurrent access.  Calling this capability will invalidate the Lock capability.
}