# Class: Concurrent::Cancellation

Inherits:
  Synchronization::Object
  - Object
  - Synchronization::Object
  - Concurrent::Cancellation
  show all

Defined in:
  lib-edge/concurrent/edge/cancellation.rb

## Overview

Note:

Edge Features are under active development and may change frequently.

- Deprecations are not added before incompatible changes.
- Edge version: major is always 0, minor bump means incompatible change, patch bump means compatible change.
- Edge features may also lack tests and documentation.
- Features developed in `concurrent-ruby-edge` are expected to move to `concurrent-ruby` when finalised.

Provides tools for cooperative cancellation. Inspired by https://msdn.microsoft.com/en-us/library/dd537607(v=vs.110).aspx

Examples:

    # Create new cancellation. `cancellation` is used for cancelling, `token` is passed down to
    # tasks for cooperative cancellation
    cancellation, token = Concurrent::Cancellation.create
    Thread.new(token) do |token|
      # Count 1+1 (simulating some other meaningful work) repeatedly
      # until the token is cancelled through cancellation.
      token.loop_until_canceled { 1+1 }
    end
    sleep 0.1
    cancellation.cancel # Stop the thread by cancelling

## Defined Under Namespace

Classes: Token

## Class Method Summary collapse

- .create(resolvable_future_or_event = Promises.resolvable_event, *resolve_args) ⇒ Array(Cancellation, Cancellation::Token)

  Creates the cancellation object.

## Instance Method Summary collapse

- #cancel(raise_on_repeated_call = true) ⇒ true, false

  Cancel this cancellation.

- #canceled? ⇒ true, false

  Is the cancellation cancelled?.

- #to_s ⇒ String (also: #inspect)

  Short string representation.

- #token ⇒ Token

  Returns the token associated with the cancellation.

## Class Method Details

### .create(resolvable_future_or_event = Promises.resolvable_event, *resolve_args) ⇒ `Array(Cancellation, Cancellation::Token)`

Creates the cancellation object. Returns both the cancellation and the token for convenience.

Examples:

    cancellation, token = Concurrent::Cancellation.create

Parameters:

- resolve_args (`Object`) —

  resolve_args Arguments which are used when resolve method is called on resolvable_future_or_event

- resolvable_future_or_event (`Promises::Resolvable`) (defaults to: `Promises.resolvable_event`) —

  resolvable used to track cancellation. Can be retrieved by `token.to_future` ot `token.to_event`.

Returns:

- (`Array(Cancellation, Cancellation::Token)`)

    29
    30
    31
    32

    # File 'lib-edge/concurrent/edge/cancellation.rb', line 29

    def self.create(resolvable_future_or_event = Promises.resolvable_event, *resolve_args)
      cancellation = new(resolvable_future_or_event, *resolve_args)
      [cancellation, cancellation.token]
    end

## Instance Method Details

### #cancel(raise_on_repeated_call = true) ⇒ `true`, `false`

Cancel this cancellation. All executions depending on the token will cooperatively stop.

Returns:

- (`true`, `false`)

Raises:

- when cancelling for the second tim

    45
    46
    47

    # File 'lib-edge/concurrent/edge/cancellation.rb', line 45

    def cancel(raise_on_repeated_call = true)
      !!@Cancel.resolve(*@ResolveArgs, raise_on_repeated_call)
    end

### #canceled? ⇒ `true`, `false`

Is the cancellation cancelled?

Returns:

- (`true`, `false`)

    51
    52
    53

    # File 'lib-edge/concurrent/edge/cancellation.rb', line 51

    def canceled?
      @Cancel.resolved?
    end

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

Short string representation.

Returns:

- (`String`)

    57
    58
    59

    # File 'lib-edge/concurrent/edge/cancellation.rb', line 57

    def to_s
      format '%s canceled:%s>', super[0..-2], canceled?
    end

### #token ⇒ `Token`

Returns the token associated with the cancellation.

Returns:

- (`Token`)

    38
    39
    40

    # File 'lib-edge/concurrent/edge/cancellation.rb', line 38

    def token
      @Token
    end