# class Sync::RWLock

- Sync::RWLock
- Reference
- Object

##
Overview

A multiple readers and exclusive writer lock to protect critical sections.

Multiple fibers can acquire the shared lock (read) to allow some critical sections to run concurrently. However a single fiber can acquire the exclusive lock at a time to protect a single critical section to ever run in parallel. When the lock has been acquired in exclusive mode, no other fiber can lock it, be it in shared or exclusive mode.

For example, the shared mode can allow to read one or many resources, albeit the resources must be safe to be accessed in such manner, while the exclusive mode allows to safely replace or mutate the resources with the guarantee that nothing else is accessing said resources.

The implementation doesn't favor readers or writers in particular.

NOTE Consider `Shared(T)` to protect a value `T` with a `RWLock`.

##
Included Modules

- Sync::Lockable

##
Defined in:

sync/rw_lock.cr

##
Constructors

- .new(type : Type = :checked)

##
Instance Method Summary

- #lock_read : Nil

  Acquires the shared (read) lock.

- #lock_write : Nil

  Acquires the exclusive (write) lock.

- #read(& : -> U) : U forall U

  Acquires the shared (read) lock for the duration of the block.

- #try_lock_read? : Bool

  Tries to acquire the shared (read) lock without blocking.

- #try_lock_write? : Bool

  Tries to acquire the exclusive (write) lock without blocking.

- #unlock_read : Nil

  Releases the shared (read) lock.

- #unlock_write : Nil

  Releases the exclusive (write) lock.

- #write(& : -> U) : U forall U

  Acquires the exclusive (write) lock for the duration of the block.

### 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(type : Type = :checked) #

##
Instance Method Detail

def lock_read : Nil #

Acquires the shared (read) lock.

Multiple fibers can acquire the shared (read) lock at the same time. Blocks the calling fiber if the exclusive (write) lock is held.

WARNING the shared lock is technically reentrant but any attempt to relock read can result in a deadlock if another fiber is trying to lock write!

def lock_write : Nil #

Acquires the exclusive (write) lock. Blocks the calling fiber while the shared or exclusive (write) lock is held.

def read(& : -> U) : U forall U #

Acquires the shared (read) lock for the duration of the block.

Multiple fibers can acquire the shared (read) lock at the same time. The block will never run concurrently to an exclusive (write) lock.

WARNING the shared lock is technically reentrant but any attempt to relock read can result in a deadlock if another fiber is trying to lock write!

def try_lock_read? : Bool #

Tries to acquire the shared (read) lock without blocking. Returns true when acquired, otherwise returns false immediately.

def try_lock_write? : Bool #

Tries to acquire the exclusive (write) lock without blocking. Returns true when acquired, otherwise returns false immediately.

def unlock_read : Nil #

Releases the shared (read) lock.

Every fiber that locked must unlock to actually release the reader lock (so a writer can lock). If a fiber locked multiple times (reentrant behavior) then it must unlock that many times.

def unlock_write : Nil #

Releases the exclusive (write) lock.

def write(& : -> U) : U forall U #

Acquires the exclusive (write) lock for the duration of the block.

Only one fiber can acquire the exclusive (write) lock at the same time. The block will never run concurrently to a shared (read) lock or another exclusive (write) lock.