RWReadMode
- The "read permission" token used for RWARCRWWriteMode
- The "write permission" token used for RWARCARC
Condvar
- As sync::condvar, a mechanism for unlock-and-descheduling and signalling.MutexARC
- An ARC with mutable data protected by a blocking mutex.RWARC
- A dual-mode ARC protected by a reader-writer lockfor & Condvar
for & MutexARC<T>
for & RWARC<T>
for & RWWriteMode<T>
for & RWReadMode<T>
ARC
- Create an atomically reference counted wrapper.MutexARC
- Create a mutex-protected ARC with the supplied data.PoisonOnFail
RWARC
- Create a reader/writer ARC with the supplied data.clone
- Duplicate an atomically reference counted wrapper.get
- Access the underlying data in an atomically reference counted wrapper.mutex_arc_with_condvars
- Create a mutex-protected ARC with the supplied data and a specified number of condvars (as sync::mutex_with_condvars).rw_arc_with_condvars
- Create a reader/writer ARC with the supplied data and a specified number of condvars (as sync::rwlock_with_condvars).unwrap
- Retrieve the data back out of the ARCunwrap_mutex_arc
- Retrieves the data, blocking until all other references are dropped, exactly as arc::unwrap.unwrap_rw_arc
- Retrieves the data, blocking until all other references are dropped, exactly as arc::unwrap.RWReadMode
The "read permission" token used for RWARC.write_downgrade().
pub RWReadMode((& T, sync::RWlockReadMode))
RWWriteMode
The "write permission" token used for RWARC.write_downgrade().
pub RWWriteMode((& mut T, sync::RWlockWriteMode, PoisonOnFail))
ARC
struct ARC <T: Const Send>{
x: SharedMutableState<T>,
}
Condvar
pub struct Condvar {
is_mutex: bool,
failed: & mut bool,
cond: & sync::Condvar,
}
As sync::condvar, a mechanism for unlock-and-descheduling and signalling.
MutexARC
struct MutexARC <T: Send>{
x: SharedMutableState<MutexARCInner<T>>,
}
An ARC with mutable data protected by a blocking mutex.
RWARC
struct RWARC <T: Const Send>{
x: SharedMutableState<RWARCInner<T>>,
mut cant_nest: (),
}
A dual-mode ARC protected by a reader-writer lock. The data can be accessed mutably or immutably, and immutably-accessing tasks may run concurrently.
Unlike mutex_arcs, rw_arcs are safe, because they cannot be nested.
& Condvar
wait
fn wait()
Atomically exit the associated ARC and block until a signal is sent.
wait_on
fn wait_on(condvar_id: uint)
Atomically exit the associated ARC and block on a specified condvar until a signal is sent on that same condvar (as sync::cond.wait_on).
wait() is equivalent to wait_on(0).
signal
fn signal() -> bool
Wake up a blocked task. Returns false if there was no blocked task.
signal_on
fn signal_on(condvar_id: uint) -> bool
Wake up a blocked task on a specified condvar (as sync::cond.signal_on). Returns false if there was no blocked task.
broadcast
fn broadcast() -> uint
Wake up all blocked tasks. Returns the number of tasks woken.
broadcast_on
fn broadcast_on(condvar_id: uint) -> uint
Wake up all blocked tasks on a specified condvar (as sync::cond.broadcast_on). Returns Returns the number of tasks woken.
& MutexARC<T>
clone
fn clone() -> MutexARC<T>
Duplicate a mutex-protected ARC, as arc::clone.
access
fn access<U>(blk: fn&(x: & mut T) -> U) -> U
Access the underlying mutable data with mutual exclusion from other tasks. The argument closure will be run with the mutex locked; all other tasks wishing to access the data will block until the closure finishes running.
The reason this function is 'unsafe' is because it is possible to construct a circular reference among multiple ARCs by mutating the underlying data. This creates potential for deadlock, but worse, this will guarantee a memory leak of all involved ARCs. Using mutex ARCs inside of other ARCs is safe in absence of circular references.
If you wish to nest mutex_arcs, one strategy for ensuring safety at runtime is to add a "nesting level counter" inside the stored data, and when traversing the arcs, assert that they monotonically decrease.
Failing while inside the ARC will unlock the ARC while unwinding, so that other tasks won't block forever. It will also poison the ARC: any tasks that subsequently try to access it (including those already blocked on the mutex) will also fail immediately.
access_cond
fn access_cond<U>(blk: fn&(x: &x/mut T, c: &c/Condvar) -> U) -> U
As access(), but with a condvar, as sync::mutex.lock_cond().
& RWARC<T>
clone
fn clone() -> RWARC<T>
Duplicate a rwlock-protected ARC, as arc::clone.
write
fn write<U>(blk: fn&(x: & mut T) -> U) -> U
Access the underlying data mutably. Locks the rwlock in write mode; other readers and writers will block.
Failing while inside the ARC will unlock the ARC while unwinding, so that other tasks won't block forever. As MutexARC.access, it will also poison the ARC, so subsequent readers and writers will both also fail.
write_cond
fn write_cond<U>(blk: fn&(x: &x/mut T, c: &c/Condvar) -> U) -> U
As write(), but with a condvar, as sync::rwlock.write_cond().
read
fn read<U>(blk: fn&(x: & T) -> U) -> U
Access the underlying data immutably. May run concurrently with other reading tasks.
Failing will unlock the ARC while unwinding. However, unlike all other access modes, this will not poison the ARC.
write_downgrade
fn write_downgrade<U>(blk: fn&(v: RWWriteMode<T>) -> U) -> U
As write(), but with the ability to atomically 'downgrade' the lock. See sync::rwlock.write_downgrade(). The RWWriteMode token must be used to obtain the &mut T, and can be transformed into a RWReadMode token by calling downgrade(), after which a &T can be obtained instead. ~ do arc.write_downgrade |write_mode| { do (&write_mode).write_cond |state, condvar| { ... exclusive access with mutable state ... } let read_mode = arc.downgrade(write_mode); do (&read_mode).read |state| { ... shared access with immutable state ... } } ~
downgrade
fn downgrade(token: RWWriteMode/&a<T>) -> RWReadMode/&a<T>
To be called inside of the write_downgrade block.
& RWWriteMode<T>
write
fn write<U>(blk: fn&(x: & mut T) -> U) -> U
Access the pre-downgrade RWARC in write mode.
write_cond
fn write_cond<U>(blk: fn&(x: &x/mut T, c: &c/Condvar) -> U) -> U
Access the pre-downgrade RWARC in write mode with a condvar.
& RWReadMode<T>
read
fn read<U>(blk: fn&(x: & T) -> U) -> U
Access the post-downgrade rwlock in read mode.
ARC
fn ARC<T: Const Send>(data: T) -> ARC<T>
Create an atomically reference counted wrapper.
MutexARC
fn MutexARC<T: Send>(user_data: T) -> MutexARC<T>
Create a mutex-protected ARC with the supplied data.
PoisonOnFail
fn PoisonOnFail(failed: &r/mut bool) -> PoisonOnFail/&r
RWARC
fn RWARC<T: Const Send>(user_data: T) -> RWARC<T>
Create a reader/writer ARC with the supplied data.
clone
fn clone<T: Const Send>(rc: & ARC<T>) -> ARC<T>
Duplicate an atomically reference counted wrapper.
The resulting two arc
objects will point to the same underlying data object. However, one of the arc
objects can be sent to another task, allowing them to share the underlying data.
get
fn get<T: Const Send>(rc: &a/ARC<T>) -> &a/T
Access the underlying data in an atomically reference counted wrapper.
mutex_arc_with_condvars
fn mutex_arc_with_condvars<T: Send>(user_data: T, num_condvars: uint) ->
MutexARC<T>
Create a mutex-protected ARC with the supplied data and a specified number of condvars (as sync::mutex_with_condvars).
rw_arc_with_condvars
fn rw_arc_with_condvars<T: Const Send>(user_data: T, num_condvars: uint) ->
RWARC<T>
Create a reader/writer ARC with the supplied data and a specified number of condvars (as sync::rwlock_with_condvars).
unwrap
fn unwrap<T: Const Send>(rc: ARC<T>) -> T
Retrieve the data back out of the ARC. This function blocks until the reference given to it is the last existing one, and then unwrap the data instead of destroying it.
If multiple tasks call unwrap, all but the first will fail. Do not call unwrap from a task that holds another reference to the same ARC; it is guaranteed to deadlock.
unwrap_mutex_arc
fn unwrap_mutex_arc<T: Send>(arc: MutexARC<T>) -> T
Retrieves the data, blocking until all other references are dropped, exactly as arc::unwrap.
Will additionally fail if another task has failed while accessing the arc.
unwrap_rw_arc
fn unwrap_rw_arc<T: Const Send>(arc: RWARC<T>) -> T
Retrieves the data, blocking until all other references are dropped, exactly as arc::unwrap.
Will additionally fail if another task has failed while accessing the arc in write mode.