class Sync::Exclusive(T)

Overview

Safely share a value T across fibers and execution contexts using a Mutex, so only one critical section can access the value at any time.

For example:

require "sync/exclusive"

class Queue
  @@running : Sync::Exclusive.new([] of Queue)

  def self.on_started(queue)
    @@running.lock(&.push(queue))
  end

  def self.on_stopped(queue)
    @@running.lock(&.delete(queue))
  end

  def self.each(&)
    @@running.lock do |list|
      list.each { |queue| yield queue }
    end
  end
end

Consider an Exclusive(T) if your workload mostly needs to own the value, and most, if not all, critical sections need to mutate the inner state of the value for example.

Included Modules

Defined in:

sync/exclusive.cr

Constructors

Instance Method Summary

Instance methods inherited from class Reference

==(other : self)
==(other : JSON::Any)
==(other : YAML::Any)
==(other) ==, dup dup, hash(hasher) hash, initialize initialize, inspect(io : IO) : Nil inspect, object_id : UInt64 object_id, pretty_print(pp) : Nil pretty_print, same?(other : Reference) : Bool
same?(other : Nil) same?, to_s(io : IO) : Nil to_s

Constructor methods inherited from class Reference

new new, unsafe_construct(address : Pointer, *args, **opts) : self unsafe_construct

Class methods inherited from class Reference

pre_initialize(address : Pointer) pre_initialize

Instance methods inherited from class Object

! : Bool !, !=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other) ===, =~(other) =~, as(type : Class) as, as?(type : Class) as?, class class, dup dup, hash(hasher)
hash hash, in?(collection : Object) : Bool
in?(*values : Object) : Bool in?, inspect(io : IO) : Nil
inspect : String inspect, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, not_nil!(message)
not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, responds_to?(name : Symbol) : Bool responds_to?, tap(&) tap, to_json(io : IO) : Nil
to_json : String to_json, to_pretty_json(indent : String = " ") : String
to_pretty_json(io : IO, indent : String = " ") : Nil to_pretty_json, to_s(io : IO) : Nil
to_s : String to_s, to_yaml(io : IO) : Nil
to_yaml : String to_yaml, try(&) try, unsafe_as(type : T.class) forall T unsafe_as

Class methods inherited from class Object

from_json(string_or_io : String | IO, root : String)
from_json(string_or_io : String | IO) from_json, from_yaml(string_or_io : String | IO) from_yaml

Macros inherited from class Object

class_getter(*names, &block) class_getter, class_getter!(*names) class_getter!, class_getter?(*names, &block) class_getter?, class_property(*names, &block) class_property, class_property!(*names) class_property!, class_property?(*names, &block) class_property?, class_setter(*names) class_setter, def_clone def_clone, def_equals(*fields) def_equals, def_equals_and_hash(*fields) def_equals_and_hash, def_hash(*fields) def_hash, delegate(*methods, to object) delegate, forward_missing_to(delegate) forward_missing_to, getter(*names, &block) getter, getter!(*names) getter!, getter?(*names, &block) getter?, property(*names, &block) property, property!(*names) property!, property?(*names, &block) property?, setter(*names) setter

Constructor Detail

def self.new(value : T, type : Type = :checked) #

[View source]

Instance Method Detail

def get : T #

Locks the mutex and returns the value. Unlocks before returning.

Always acquires the lock, so reading the value is synchronized in relation with the other methods. However, safely accessing the returned value entirely depends on the safety of T.

Prefer #lock(&.dup) or #lock(&.clone) to get a shallow or deep copy of the value instead.

WARNING Breaks the mutual exclusion guarantee since the returned value outlives the lock, the value can be accessed concurrently to the synchronized methods.


[View source]
def lock(& : T -> U) : U forall U #

Locks the mutex and yields the value. The lock is released before returning.

The value is owned for the duration of the block, and can be safely mutated.

WARNING The value musn't be retained and accessed after the block has returned.


[View source]
def replace(& : T -> T) : Nil #

Locks the mutex, yields the value and eventually replaces the value with the one returned by the block. The lock is released before returning.

The current value is now owned: it can be safely retained and mutated even after the block returned.

WARNING The new value musn't be retained and accessed after the block has returned.


[View source]
def set(value : T) : Nil #

Locks the mutex and sets the value. Unlocks the mutex before returning.

Always acquires and releases the lock, so writing the value is always synchronized with the other methods.


[View source]
def unsafe_get : T #

Returns the value without any synchronization.

WARNING Breaks the mutual exclusion constraint! Should only be called after acquiring the lock.


[View source]
def unsafe_set(value : T) : T #

Sets the value without any synchronization.

WARNING Breaks the mutual exclusion constraint! Should only be called after acquiring the lock.


[View source]