jon.recoil.org

Module Extended.DataSource

Data defines pointers to some data within a capsule

Sourcetype ('a, 'k) t

('a, 'k) t represents a value of type 'a that belongs to the capsule 'k. It crosses both contention and portability, so can be freely passed to other threads.

Its inner value may not be accessed directly. Instead, you can unwrap it if you have an uncontended Access.t token for the capsule. If you only want to access the immutable parts of its inner value, you can alternatively use get_id.

These functions are the most common way to interact with capsules.

Sourceval create : (unit -> 'a) @ local once portable -> ('a, 'k) t

create f runs f within some capsule 'k, and returns a data point to the result. Since f can be run within an arbitrary capsule, it must be portable. As a result, f can't use data that might belong to another capsule, and isolation between capsules is maintained. If f produces a unique result, the resulting Data.t is unique.

Sourceval wrap : access:'k Access.t -> 'a -> ('a, 'k) t

wrap ~access v adds v of some type 'a to capsule 'k, and returns a ('a, 'k) Capsule.Data.t. ~access must be uncontended, which means 'k is always the current capsule. v itself must also be uncontended, meaning it must have been created within the current capsule.

wrap is templated over locality, which means that if you only have access to v locally, you can create a local data value; use

  Capsule.Data.wrap [@mode local]

to use the version that accepts a local value v and produces a local Capsule.Data.t.

Sourceval unwrap : ('a : value mod nonportable) 'k. access:'k Access.t -> ('a, 'k) t -> 'a

unwrap ~access t returns the value of t, which lives in the capsule 'k. ~access is either uncontended or shared, which means that 'k is always the current capsule.

If ~access is uncontended, we have sole access to the capsule 'k, and it is safe to access the value of t as uncontended.

If ~access is shared, other threads might have simultaneous shared access to 'k, and access to the value of t is limited to shared, and must cross portable.

unwrap is templated over locality, which means that a local Capsule.Data.t will grant you a local value.

These functions enable more complicated manipulation of capsules.

Sourceval return : 'a @ portable -> ('a, 'k) t

return v creates a pointer to a value v injected into the capsule 'k. The value must cross contention and be portable, since it is being moved from the current capsule into the capsule 'k.

Sourceval both : ('a, 'k) t -> ('b, 'k) t -> ('a * 'b, 'k) t

both t1 t2 is a pointer to a pair of the values of t1 and t2.

Sourceval fst : ('a * _, 'k) t -> ('a, 'k) t

fst t gives a pointer to the first value inside t

Sourceval snd : (_ * 'b, 'k) t -> ('b, 'k) t

snd t gives a pointer to the second value inside t

Sourceval get_id : ('a : value mod portable) 'k. ('a, 'k) t -> 'a @ contended

get_id t retrieves the value of t directly. The result is a value within 'k, which is not guaranteed to be the current capsule. As such, it is marked as contended, and must always be portable. Likely only useful if the capsule has already been map'd, as capsules do not usually contain portable values.

These functions enable more complicated manipulation of capsules.

Sourceval idx : ('a, 'k) t -> ('a, 'b) idx_imm -> ('b, 'k) t

idx t i is a pointer to the value at i in t.

See Ox.Idx for more information on indexes.