Class: Concurrent::Cancellation — Concurrent

Class List Method List File List

# Class: Concurrent::Cancellation

Inherits:
  Synchronization::Object
  - Object
  - Synchronization::Object
  - Concurrent::Cancellation
  show all
Defined in:
  lib/concurrent/edge/cancellation.rb

## Overview

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)

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

  Creates the cancellation object.

## Instance Method Summary (collapse)

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

  Cancel this cancellation.

- - (true, false) canceled?

  Is the cancellation cancelled?.

- - (String) to_s (also: #inspect)

  Short string representation.

- - (Token) token

  Returns the token associated with the cancellation.

## Class Method Details

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

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)`)

    28
    29
    30
    31
    # File 'lib/concurrent/edge/cancellation.rb', line 28

    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

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

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

Returns:

- (`true`, `false`)

Raises:

- when cancelling for the second tim

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

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

### - (`true`, `false`) canceled?

Is the cancellation cancelled?

Returns:

- (`true`, `false`)

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

    def canceled?
      @Cancel.resolved?
    end

### - (`String`) to_s Also known as: inspect

Short string representation.

Returns:

- (`String`)

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

    def to_s
      format '<#%s:0x%x canceled:%s>', self.class, object_id << 1, canceled?
    end

### - (`Token`) token

Returns the token associated with the cancellation.

Returns:

- (`Token`)

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

    def token
      @Token
    end