Module: Concurrent::Concern::Dereferenceable — Concurrent Ruby

# Module: Concurrent::Concern::Dereferenceable

Included in:
  Obligation, MVar, TimerTask

Defined in:
  lib/concurrent-ruby/concurrent/concern/dereferenceable.rb

## Overview

Object references in Ruby are mutable. This can lead to serious problems when the `#value` of a concurrent object is a mutable reference. Which is always the case unless the value is a `Fixnum`, `Symbol`, or similar "primitive" data type. Most classes in this library that expose a `#value` getter method do so using the `Dereferenceable` mixin module.

## Copy Options

Object references in Ruby are mutable. This can lead to serious problems when the #value of an object is a mutable reference. Which is always the case unless the value is a `Fixnum`, `Symbol`, or similar "primitive" data type. Each instance can be configured with a few options that can help protect the program from potentially dangerous operations. Each of these options can be optionally set when the object instance is created:

- `:dup_on_deref` When true the object will call the `#dup` method on the `value` object every time the `#value` method is called (default: false)
- `:freeze_on_deref` When true the object will call the `#freeze` method on the `value` object every time the `#value` method is called (default: false)
- `:copy_on_deref` When given a `Proc` object the `Proc` will be run every time the `#value` method is called. The `Proc` will be given the current `value` as its only argument and the result returned by the block will be the return value of the `#value` call. When `nil` this option will be ignored (default: nil)

When multiple deref options are set the order of operations is strictly defined. The order of deref operations is:

- `:copy_on_deref`
- `:dup_on_deref`
- `:freeze_on_deref`

Because of this ordering there is no need to `#freeze` an object created by a provided `:copy_on_deref` block. Simply set `:freeze_on_deref` to `true`. Setting both `:dup_on_deref` to `true` and `:freeze_on_deref` to `true` is as close to the behavior of a "pure" functional language (like Erlang, Clojure, or Haskell) as we are likely to get in Ruby.

## Instance Method Summary collapse

- #value ⇒ Object (also: #deref)

  Return the value this object represents after applying the options specified by the `#set_deref_options` method.

## Instance Method Details

### #value ⇒ `Object` Also known as: deref

Return the value this object represents after applying the options specified by the `#set_deref_options` method.

Returns:

- (`Object`) —

  the current value of the object

    21
    22
    23
    # File 'lib/concurrent-ruby/concurrent/concern/dereferenceable.rb', line 21

    def value
      synchronize { apply_deref_options(@value) }
    end