jon.recoil.org

Module Capsule_prim.KeySource

Keys represent the ownership of the capsule.

Keys represent the ownership of the capsule.

Sourcetype 'k t : void mod contended external_ forkable many portable unyielding

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

Sourcetype packed =
  1. | P : 'k t -> packed
Sourcetype 'k boxed : value mod contended external_ forkable many portable

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

Sourceval box : 'k t @ unique -> 'k boxed @ unique @@ portable
Sourceval unbox : 'k boxed @ unique -> 'k t @ unique @@ portable
Sourceval box_aliased : 'k t -> 'k boxed @@ portable
Sourceval unbox_aliased : 'k boxed -> 'k t @@ portable
Sourceval with_password : ('a : value_or_null) 'k. 'k t @ unique -> f:('k Capsule_prim__.Prim.Password.t @ local -> 'a @ unique) @ local once -> #('a * 'k t) @ unique @@ 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.

Sourceval with_password_local : ('a : value_or_null) 'k. 'k t @ unique -> f:('k Capsule_prim__.Prim.Password.t @ local -> 'a @ local) @ local once -> 'a @ local @@ 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.

Sourceval with_password_shared : ('a : value_or_null) 'k. 'k t @ local -> f: ('k Capsule_prim__.Prim.Password.Shared.t @ local forkable -> '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.

Sourceval with_password_shared_local : ('a : value_or_null) 'k. 'k t -> f: ('k Capsule_prim__.Prim.Password.Shared.t @ local -> 'a @ local) @ local once -> 'a @ local @@ portable

As with_password_shared, but returns a local value.

Sourceval access : ('a : value_or_null) 'k. 'k t @ unique -> f: ('k Capsule_prim__.Prim.Access.t -> 'a @ unique once portable contended) @ local once portable -> #('a * 'k t) @ unique once portable contended @@ 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.

Sourceval access_shared : ('a : value_or_null) 'k. 'k t -> f: ('k Capsule_prim__.Prim.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.

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

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

Sourceval destroy : 'k t @ local unique -> 'k Capsule_prim__.Prim.Access.t @@ portable

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

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

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