# Class: Concurrent::Actor::Reference

Inherits:
  Object
  - Object
  - Concurrent::Actor::Reference
  show all

Includes:
  PublicDelegations, TypeCheck

Defined in:
  lib-edge/concurrent/actor/reference.rb

## Overview

Reference is public interface of Actor instances. It is used for sending messages and can be freely passed around the application. It also provides some basic information about the actor, see PublicDelegations.

    AdHoc.spawn('printer') { -> message { puts message } }
    # => #<Concurrent::Actor::Reference:0x7fd0d2883218 /printer (Concurrent::Actor::Utils::AdHoc)>
    #                                   ^object_id     ^path     ^context class

## Instance Method Summary collapse

- #==(other) ⇒ undocumented
- #ask(message, future = Concurrent::Promises.resolvable_future) ⇒ Promises::Future (also: #ask_op)

  testing and when it returns very shortly.

- #ask!(message, future = Concurrent::Promises.resolvable_future) ⇒ Object

  Sends the message synchronously and blocks until the message is processed.

- #dead_letter_routing ⇒ undocumented
- #map(messages) ⇒ undocumented
- #message(message, future = nil) ⇒ undocumented

  behaves as #tell when no future and as #ask when future.

- #tell(message) ⇒ Reference (also: #<<)

  Sends the message asynchronously to the actor and immediately returns `self` (the reference) allowing to chain message telling.

- #to_s ⇒ undocumented (also: #inspect)
- #Child!(value, *types) ⇒ undocumented included from TypeCheck
- #Child?(value, *types) ⇒ Boolean included from TypeCheck
- #context_class ⇒ undocumented (also: #actor_class) included from PublicDelegations
- #executor ⇒ undocumented included from PublicDelegations
- #Match!(value, *types) ⇒ undocumented included from TypeCheck
- #Match?(value, *types) ⇒ Boolean included from TypeCheck
- #name ⇒ undocumented included from PublicDelegations
- #parent ⇒ undocumented included from PublicDelegations
- #path ⇒ undocumented included from PublicDelegations
- #reference ⇒ undocumented (also: #ref) included from PublicDelegations
- #Type!(value, *types) ⇒ undocumented included from TypeCheck
- #Type?(value, *types) ⇒ Boolean included from TypeCheck

## Instance Method Details

### #==(other) ⇒ `undocumented`

    100
    101
    102

    # File 'lib-edge/concurrent/actor/reference.rb', line 100

    def ==(other)
      Type? other, self.class and other.send(:core) == core
    end

### #ask(message, future = Concurrent::Promises.resolvable_future) ⇒ `Promises::Future` Also known as: ask_op

Note:

it's a good practice to use tell whenever possible. Ask should be used only for

Note:

it's a good practice to use #tell whenever possible. Results can be send back with other messages. Ask should be used only for testing and when it returns very shortly. It can lead to deadlock if all threads in global_io_executor will block on while asking. It's fine to use it form outside of actors and global_io_executor.

testing and when it returns very shortly. It can lead to deadlock if all threads in global_io_executor will block on while asking. It's fine to use it form outside of actors and global_io_executor.

Examples:

    adder = AdHoc.spawn('adder') { -> message { message + 1 } }
    adder.ask(1).value # => 2
    adder.ask(nil).wait.reason # => #<NoMethodError: undefined method `+' for nil:NilClass>

Parameters:

- message (`Object`)
- future (`Promises::Future`) (defaults to: `Concurrent::Promises.resolvable_future`) —

  to be fulfilled be message's processing result

Returns:

- (`Promises::Future`) —

  supplied future

    54
    55
    56

    # File 'lib-edge/concurrent/actor/reference.rb', line 54

    def ask(message, future = Concurrent::Promises.resolvable_future)
      message message, future
    end

### #ask!(message, future = Concurrent::Promises.resolvable_future) ⇒ `Object`

Note:

it's a good practice to use #tell whenever possible. Results can be send back with other messages. Ask should be used only for testing and when it returns very shortly. It can lead to deadlock if all threads in global_io_executor will block on while asking. It's fine to use it form outside of actors and global_io_executor.

Sends the message synchronously and blocks until the message is processed. Raises on error.

Examples:

    adder = AdHoc.spawn('adder') { -> message { message + 1 } }
    adder.ask!(1) # => 2

Parameters:

- message (`Object`)
- future (`Promises::Future`) (defaults to: `Concurrent::Promises.resolvable_future`) —

  to be fulfilled be message's processing result

Returns:

- (`Object`) —

  message's processing result

Raises:

- (`Exception`) —

  future.reason if future is #rejected?

    75
    76
    77

    # File 'lib-edge/concurrent/actor/reference.rb', line 75

    def ask!(message, future = Concurrent::Promises.resolvable_future)
      ask(message, future).value!
    end

### #dead_letter_routing ⇒ `undocumented`

See Also:

- AbstractContext#dead_letter_routing

    90
    91
    92

    # File 'lib-edge/concurrent/actor/reference.rb', line 90

    def dead_letter_routing
      core.dead_letter_routing
    end

### #map(messages) ⇒ `undocumented`

    79
    80
    81

    # File 'lib-edge/concurrent/actor/reference.rb', line 79

    def map(messages)
      messages.map { |m| self.ask(m) }
    end

### #message(message, future = nil) ⇒ `undocumented`

behaves as #tell when no future and as #ask when future

    84
    85
    86
    87

    # File 'lib-edge/concurrent/actor/reference.rb', line 84

    def message(message, future = nil)
      core.on_envelope Envelope.new(message, future, Actor.current || Thread.current, self)
      return future ? future.with_hidden_resolvable : self
    end

### #tell(message) ⇒ `Reference` Also known as: <<

Sends the message asynchronously to the actor and immediately returns `self` (the reference) allowing to chain message telling.

Examples:

    printer = AdHoc.spawn('printer') { -> message { puts message } }
    printer.tell('ping').tell('pong')
    printer << 'ping' << 'pong'
    # => 'ping'\n'pong'\n'ping'\n'pong'\n

Parameters:

- message (`Object`)

Returns:

- (`Reference`) —

  self

    32
    33
    34

    # File 'lib-edge/concurrent/actor/reference.rb', line 32

    def tell(message)
      message message, nil
    end

### #to_s ⇒ `undocumented` Also known as: inspect

    94
    95
    96

    # File 'lib-edge/concurrent/actor/reference.rb', line 94

    def to_s
      format '%s %s (%s)>', super[0..-2], path, actor_class
    end

### #Child!(value, *types) ⇒ `undocumented` Originally defined in module TypeCheck

### #Child?(value, *types) ⇒ `Boolean` Originally defined in module TypeCheck

Returns:

- (`Boolean`)

### #context_class ⇒ `undocumented` Also known as: actor_class Originally defined in module PublicDelegations

See Also:

- Core#context_class

### #executor ⇒ `undocumented` Originally defined in module PublicDelegations

See Also:

- Core#executor

### #Match!(value, *types) ⇒ `undocumented` Originally defined in module TypeCheck

### #Match?(value, *types) ⇒ `Boolean` Originally defined in module TypeCheck

Returns:

- (`Boolean`)

### #name ⇒ `undocumented` Originally defined in module PublicDelegations

See Also:

- Core#name

### #parent ⇒ `undocumented` Originally defined in module PublicDelegations

See Also:

- Core#parent

### #path ⇒ `undocumented` Originally defined in module PublicDelegations

See Also:

- Core#path

### #reference ⇒ `undocumented` Also known as: ref Originally defined in module PublicDelegations

See Also:

- Core#reference

### #Type!(value, *types) ⇒ `undocumented` Originally defined in module TypeCheck

### #Type?(value, *types) ⇒ `Boolean` Originally defined in module TypeCheck

Returns:

- (`Boolean`)