Enum RWReadMode

The "read permission" token used for RWARC.write_downgrade().

Variants

Enum RWWriteMode

The "write permission" token used for RWARC.write_downgrade().

Variants

Struct ARC

struct ARC <T: Const Send>{
    x: SharedMutableState<T>,
}

Struct Condvar

pub struct Condvar {
        is_mutex: bool,
        failed: & mut bool,
        cond: & sync::Condvar,
    }

As sync::condvar, a mechanism for unlock-and-descheduling and signalling.

Struct MutexARC

struct MutexARC <T: Send>{
    x: SharedMutableState<MutexARCInner<T>>,
}

An ARC with mutable data protected by a blocking mutex.

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

Implementation for & Condvar

Method wait

fn wait()

Atomically exit the associated ARC and block until a signal is sent.

Method 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).

Method signal

fn signal() -> bool

Wake up a blocked task. Returns false if there was no blocked task.

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

Method broadcast

fn broadcast() -> uint

Wake up all blocked tasks. Returns the number of tasks woken.

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

Implementation for & MutexARC<T>

Method clone

fn clone() -> MutexARC<T>

Duplicate a mutex-protected ARC, as arc::clone.

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

Failure

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.

Method 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().

Implementation for & RWARC<T>

Method clone

fn clone() -> RWARC<T>

Duplicate a rwlock-protected ARC, as arc::clone.

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

Failure

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.

Method 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().

Method read

fn read<U>(blk: fn&(x: & T) -> U) -> U

Access the underlying data immutably. May run concurrently with other reading tasks.

Failure

Failing will unlock the ARC while unwinding. However, unlike all other access modes, this will not poison the ARC.

Method 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 ... } } ~

Method downgrade

fn downgrade(token: RWWriteMode/&a<T>) -> RWReadMode/&a<T>

To be called inside of the write_downgrade block.

Implementation for & RWWriteMode<T>

Method write

fn write<U>(blk: fn&(x: & mut T) -> U) -> U

Access the pre-downgrade RWARC in write mode.

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

Implementation for & RWReadMode<T>

Method read

fn read<U>(blk: fn&(x: & T) -> U) -> U

Access the post-downgrade rwlock in read mode.

Function ARC

fn ARC<T: Const Send>(data: T) -> ARC<T>

Create an atomically reference counted wrapper.

Function MutexARC

fn MutexARC<T: Send>(user_data: T) -> MutexARC<T>

Create a mutex-protected ARC with the supplied data.

Function PoisonOnFail

fn PoisonOnFail(failed: &r/mut bool) -> PoisonOnFail/&r

Function RWARC

fn RWARC<T: Const Send>(user_data: T) -> RWARC<T>

Create a reader/writer ARC with the supplied data.

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

Function get

fn get<T: Const Send>(rc: &a/ARC<T>) -> &a/T

Access the underlying data in an atomically reference counted wrapper.

Function 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).

Function 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).

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

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

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