Sync::ConditionVariable - Crystal 1.20.2

# class Sync::ConditionVariable

- Sync::ConditionVariable
- Reference
- Object

##
Overview

Suspend a fiber until notified.

A `ConditionVariable` can be associated to any `Lockable`.

While one `Lockable` can be associated to multiple `ConditionVariable`, one `ConditionVariable` can only be associated to a single `Lockable` (one-to-many relation).

Condition variables may only be preferred over `WaitGroup` or `Channel(T)` for specific scenarios that need to wake a single fiber (signal) or all waiting fibers (broadcast). For example:

Prefer `Channel(T)` to pass a local resource around over a `Mutex` and `ConditionVariable` to protect a global resource, but sometimes you don't need to pass a value and only need to repeatedly signal one or multiple workers, in which case a condition variable might be useful.

Prefer `WaitGroup(T)` if you need to wait for a task to complete, or for a set of workers to be ready (specific lifetimes), but sometimes you want to repeatedly or sporadically notify one or many workers that may be added or removed concurrently (unbounded lifetimes), in which case a condition variable might be useful.

##
Defined in:

sync/condition_variable.cr

##
Constructors

- .new(lock : Lockable)

##
Instance Method Summary

- #broadcast : Nil

  Wakes up all waiting fibers at once.

- #signal : Nil

  Wakes up one waiting fiber.

- #wait : Nil

  Blocks the calling fiber until the condition variable is signaled.

### 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(lock : Lockable) #

##
Instance Method Detail

def broadcast : Nil #

Wakes up all waiting fibers at once.

You can wake a single waiting fiber with `#signal`.

def signal : Nil #

Wakes up one waiting fiber.

For `RWLock` and `Shared(T)` all readers can acquire, thus multiple readers might be woken at once, but only one writer can acquire, thus only one reader will be woken at a time.

You can wake all waiting fibers with `#broadcast`.

def wait : Nil #

Blocks the calling fiber until the condition variable is signaled.

The lock must be held upon calling. Releases lock before waiting, so any other fiber can acquire the lock while the calling fiber is waiting. The lock is re-acquired before returning.

A `RWLock` and `Shared(T)` can be held in either read or write mode, the lock will be reacquired in the same mode (read or write) before returning.

The calling fiber will be woken by `#signal` or `#broadcast`.