Key (capsule0.capsule0.expert.Capsule

type 'k t

'k t @ unique represents the exclusive ownership of the capsule 'k. The uniqueness of 'k t guarantees that only one thread can access the capsule at a time.

Obtaining a unique 'k t requires either calling Capsule.create or acquiring a synchronization primitive associated with 'k. Such primitives are provided by the Await library.

'k t @ aliased indicates that the key has been permanently shared, since it's avaiable aliased and therefore not available uniquely. Therefore, we can allow all threads read access to 'k.

type packed =

| P : 'k t -> packed

type 'k boxed

A boxed version of Key.t for places where you need a type with layout value.

val box : 'k t @ unique -> 'k boxed @ unique @@ portable

val unbox : 'k boxed @ unique -> 'k t @ unique @@ portable

val box_aliased : 'k t -> 'k boxed @@ portable

val unbox_aliased : 'k boxed -> 'k t @@ portable

val with_password : 
  'a 'k. 'k t @ unique ->
  (f:('k Password.t @ local -> 'a @ unique) @ local once ->
  #('a * 'k t) @ unique) @ once @@ portable

with_password k ~f runs f, providing it a password for 'k, and returns the result of f together with the key.

If f raises an exception, the key is destroyed, leaking the contents of the capsule.

val with_password_local : 
  'a 'k. 'k t @ unique ->
  (f:('k Password.t @ local -> 'a @ local) @ local once ->
  'a @ local) @ once @@ portable

with_password_local k ~f runs f, providing it a password for 'k, and returns the result of f. The key is destroyed, but the local password can be returned to provide access to the capsule.

val with_password_shared : 
  'a 'k. 'k t ->
  f:('k Password.Shared.t @ local -> 'a @ unique) @ local once ->
  'a @ unique @@ portable

with_password_shared k ~f runs f, providing it a shared password for 'k, and returns the result of f.

val with_password_shared_local : 
  'a 'k. 'k t ->
  f:('k Password.Shared.t @ local -> 'a @ local) @ local once ->
  'a @ local @@ portable

As with_password_shared, but returns a local value.

val access : 
  'a 'k. 'k t @ unique ->
  (f:('k Access.t -> 'a @ unique once portable contended) @ local once portable ->
  #('a * 'k t) @ unique once portable contended) @ once @@ portable

access k ~f runs f, providing it access to the capsule 'k, and returns the result of f together with the key.

If f raises an exception, the key is destroyed, leaking the contents of the capsule, and the exception is reraised.

val access_local : 
  'a 'k. 'k t @ unique ->
  (f:
     ('k Access.t -> 'a @ local unique once portable contended) @ local once portable ->
  #('a * 'k t) @ local unique once portable contended) @ once @@ portable

As access, but local.

val access_shared : 
  'a 'k. 'k t ->
  f:
    ('k Access.t @ shared -> 'a @ unique once portable contended) @ local once portable ->
  'a @ unique once portable contended @@ portable

access_shared k ~f runs f, providing it a shared access to 'k, and returns the result of f. Exceptions raised from f are re-raised.

val access_shared_local : 
  'a 'k. 'k t ->
  f:
    ('k Access.t @ shared -> 'a @ local unique once portable contended) @ local once portable ->
  'a @ local unique once portable contended @@ portable

As access_shared, but returns a local value.

val globalize_unique : 'k t @ local unique -> 'k t @ unique @@ portable

globalize_unique k promotes a local unique key to a global one.

val destroy : 'k t @ local unique -> 'k Access.t @@ portable

destroy k returns 'k Access.t for 'k, merging it with the current capsule. The key is destroyed.

val unsafe_mk : unit -> 'k t @ unique @@ portable

unsafe_mk () unsafely makes a unique key for an arbitrary capsule.