Class List Method List File List

# Class: Vertx::Context

Inherits:
  Object
  - Object
  - Vertx::Context
  show all
Defined in:
  /Users/julien/java/vertx-stack/stack-docs/target/rb/vertx/context.rb

## Overview

The execution context of a Proc execution.

When Vert.x provides an event to a handler or calls the start or stop methods of a Nil, the execution is associated with a `Context`.

Usually a context is an *event-loop context* and is tied to a specific event loop thread. So executions for that context always occur on that exact same event loop thread.

In the case of worker verticles and running inline blocking code a worker context will be associated with the execution which will use a thread from the worker thread pool.

When a handler is set by a thread associated with a specific context, the Vert.x will guarantee that when that handler is executed, that execution will be associated with the same context.

If a handler is set by a thread not associated with a context (i.e. a non Vert.x thread). Then a new context will be created for that handler.

In other words, a context is propagated.

This means that when a verticle is deployed, any handlers it sets will be associated with the same context - the context of the verticle.

This means (in the case of a standard verticle) that the verticle code will always be executed with the exact same thread, so you don't have to worry about multi-threaded acccess to the verticle state and you can code your application as single threaded.

This class also allows arbitrary data to be #put and #get on the context so it can be shared easily amongst different handlers of, for example, a verticle instance.

This class also provides #run_on_context which allows an action to be executed asynchronously using the same context.

## Class Method Summary (collapse)

- + (true, false) on_event_loop_thread?
  Is the current thread an event thread? NOTE! This is not always the same as calling #is_event_loop_context.
- + (true, false) on_vertx_thread?
  Is the current thread a Vert.x thread? That's either a worker thread or an event loop thread.
- + (true, false) on_worker_thread?
  Is the current thread a worker thread? NOTE! This is not always the same as calling #is_worker_context.

## Instance Method Summary (collapse)

- - (Hash{String => Object}) config
  If the context is associated with a Verticle deployment, this returns the configuration that was specified when the verticle was deployed.
- - (String) deployment_id
  If the context is associated with a Verticle deployment, this returns the deployment ID of that deployment.
- - (true, false) event_loop_context?
  Is the current context an event loop context? NOTE! when running blocking code using Vertx#execute_blocking from a standard (not worker) verticle, the context will still an event loop context and this will return true.
- - (self) exception_handler { ... }
  Set an exception handler called when the context runs an action throwing an uncaught throwable.
- - (void) execute_blocking(blockingCodeHandler = nil, ordered = nil) { ... }
  Safely execute some blocking code.
- - (Object) get(key = nil)
  Get some data from the context.
- - (Fixnum) get_instance_count
  @return the number of instances of the verticle that were deployed in the deployment (if any) related to this context.
- - (true, false) multi_threaded_worker_context?
  Is the current context a multi-threaded worker context?.
- - (::Vertx::Vertx) owner
  @return The Vertx instance that created the context.
- - (Array<String>) process_args
  The process args.
- - (void) put(key = nil, value = nil)
  Put some data in the context.
- - (true, false) remove?(key = nil)
  Remove some data from the context.
- - (void) run_on_context { ... }
  Run the specified action asynchronously on the same context, some time after the current execution has completed.
- - (true, false) worker_context?
  Is the current context a worker context? NOTE! when running blocking code using Vertx#execute_blocking from a standard (not worker) verticle, the context will still an event loop context and this will return false.

## Class Method Details

### + (`true`, `false`) on_event_loop_thread?

Is the current thread an event thread?

NOTE! This is not always the same as calling #is_event_loop_context. If you are running blocking code from an event loop context, then this will return false but #is_event_loop_context will return true.

Returns:

- (`true`, `false`) —
  true if current thread is a worker thread, false otherwise

Raises:

- (`ArgumentError`)

    63
    64
    65
    66
    67
    68
    # File '/Users/julien/java/vertx-stack/stack-docs/target/rb/vertx/context.rb', line 63

    def self.on_event_loop_thread?
      if !block_given?
        return Java::IoVertxCore::Context.java_method(:isOnEventLoopThread, []).call()
      end
      raise ArgumentError, "Invalid arguments when calling on_event_loop_thread?()"
    end

### + (`true`, `false`) on_vertx_thread?

Is the current thread a Vert.x thread? That's either a worker thread or an event loop thread

Returns:

- (`true`, `false`) —
  true if current thread is a Vert.x thread, false otherwise

Raises:

- (`ArgumentError`)

    71
    72
    73
    74
    75
    76
    # File '/Users/julien/java/vertx-stack/stack-docs/target/rb/vertx/context.rb', line 71

    def self.on_vertx_thread?
      if !block_given?
        return Java::IoVertxCore::Context.java_method(:isOnVertxThread, []).call()
      end
      raise ArgumentError, "Invalid arguments when calling on_vertx_thread?()"
    end

### + (`true`, `false`) on_worker_thread?

Is the current thread a worker thread?

NOTE! This is not always the same as calling #is_worker_context. If you are running blocking code from an event loop context, then this will return true but #is_worker_context will return false.

Returns:

- (`true`, `false`) —
  true if current thread is a worker thread, false otherwise

Raises:

- (`ArgumentError`)

    52
    53
    54
    55
    56
    57
    # File '/Users/julien/java/vertx-stack/stack-docs/target/rb/vertx/context.rb', line 52

    def self.on_worker_thread?
      if !block_given?
        return Java::IoVertxCore::Context.java_method(:isOnWorkerThread, []).call()
      end
      raise ArgumentError, "Invalid arguments when calling on_worker_thread?()"
    end

## Instance Method Details

### - (`Hash{String => Object}`) config

If the context is associated with a Verticle deployment, this returns the configuration that was specified when the verticle was deployed.

Returns:

- (`Hash{String => Object}`) —
  the configuration of the deployment or null if not a Verticle deployment

Raises:

- (`ArgumentError`)

    119
    120
    121
    122
    123
    124
    # File '/Users/julien/java/vertx-stack/stack-docs/target/rb/vertx/context.rb', line 119

    def config
      if !block_given?
        return @j_del.java_method(:config, []).call() != nil ? JSON.parse(@j_del.java_method(:config, []).call().encode) : nil
      end
      raise ArgumentError, "Invalid arguments when calling config()"
    end

### - (`String`) deployment_id

If the context is associated with a Verticle deployment, this returns the deployment ID of that deployment.

Returns:

- (`String`) —
  the deployment ID of the deployment or null if not a Verticle deployment

Raises:

- (`ArgumentError`)

    110
    111
    112
    113
    114
    115
    # File '/Users/julien/java/vertx-stack/stack-docs/target/rb/vertx/context.rb', line 110

    def deployment_id
      if !block_given?
        return @j_del.java_method(:deploymentID, []).call()
      end
      raise ArgumentError, "Invalid arguments when calling deployment_id()"
    end

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

Is the current context an event loop context?

NOTE! when running blocking code using Vertx#execute_blocking from a standard (not worker) verticle, the context will still an event loop context and this will return true.

Returns:

- (`true`, `false`) —
  true if false otherwise

Raises:

- (`ArgumentError`)

    139
    140
    141
    142
    143
    144
    # File '/Users/julien/java/vertx-stack/stack-docs/target/rb/vertx/context.rb', line 139

    def event_loop_context?
      if !block_given?
        return @j_del.java_method(:isEventLoopContext, []).call()
      end
      raise ArgumentError, "Invalid arguments when calling event_loop_context?()"
    end

### - (`self`) exception_handler { ... }

Set an exception handler called when the context runs an action throwing an uncaught throwable.

When this handler is called, Vertx#current_context will return this context.

Yields:

- the exception handler

Returns:

- (`self`)

Raises:

- (`ArgumentError`)

    217
    218
    219
    220
    221
    222
    223
    # File '/Users/julien/java/vertx-stack/stack-docs/target/rb/vertx/context.rb', line 217

    def exception_handler
      if block_given?
        @j_del.java_method(:exceptionHandler, [Java::IoVertxCore::Handler.java_class]).call((Proc.new { |event| yield(::Vertx::Util::Utils.from_throwable(event)) }))
        return self
      end
      raise ArgumentError, "Invalid arguments when calling exception_handler()"
    end

### - (`void`) execute_blocking(blockingCodeHandler = nil, ordered = nil) { ... }

This method returns an undefined value.

Safely execute some blocking code.

Executes the blocking code in the handler `blockingCodeHandler` using a thread from the worker pool.

When the code is complete the handler `resultHandler` will be called with the result on the original context (e.g. on the original event loop of the caller).

A `Future` instance is passed into `blockingCodeHandler`. When the blocking code successfully completes, the handler should call the Future#complete or Future#complete method, or the Future#fail method if it failed.

Parameters:

- blockingCodeHandler (`Proc`) (defaults to: `nil`) —
  handler representing the blocking code to run
- ordered (`true`, `false`) (defaults to: `nil`) —
  if true then if executeBlocking is called several times on the same context, the executions for that context will be executed serially, not in parallel. if false then they will be no ordering guarantees

Yields:

- handler that will be called when the blocking code is complete

Raises:

- (`ArgumentError`)

    100
    101
    102
    103
    104
    105
    106
    107
    # File '/Users/julien/java/vertx-stack/stack-docs/target/rb/vertx/context.rb', line 100

    def execute_blocking(blockingCodeHandler=nil,ordered=nil)
      if blockingCodeHandler.class == Proc && block_given? && ordered == nil
        return @j_del.java_method(:executeBlocking, [Java::IoVertxCore::Handler.java_class,Java::IoVertxCore::Handler.java_class]).call((Proc.new { |event| blockingCodeHandler.call(::Vertx::Util::Utils.safe_create(event,::Vertx::Future)) }),(Proc.new { |ar| yield(ar.failed ? ar.cause : nil, ar.succeeded ? ::Vertx::Util::Utils.from_object(ar.result) : nil) }))
      elsif blockingCodeHandler.class == Proc && (ordered.class == TrueClass || ordered.class == FalseClass) && block_given?
        return @j_del.java_method(:executeBlocking, [Java::IoVertxCore::Handler.java_class,Java::boolean.java_class,Java::IoVertxCore::Handler.java_class]).call((Proc.new { |event| blockingCodeHandler.call(::Vertx::Util::Utils.safe_create(event,::Vertx::Future)) }),ordered,(Proc.new { |ar| yield(ar.failed ? ar.cause : nil, ar.succeeded ? ::Vertx::Util::Utils.from_object(ar.result) : nil) }))
      end
      raise ArgumentError, "Invalid arguments when calling execute_blocking(blockingCodeHandler,ordered)"
    end

### - (`Object`) get(key = nil)

Get some data from the context.

Parameters:

- key (`String`) (defaults to: `nil`) —
  the key of the data

Returns:

- (`Object`) —
  the data

Raises:

- (`ArgumentError`)

    168
    169
    170
    171
    172
    173
    # File '/Users/julien/java/vertx-stack/stack-docs/target/rb/vertx/context.rb', line 168

    def get(key=nil)
      if key.class == String && !block_given?
        return ::Vertx::Util::Utils.from_object(@j_del.java_method(:get, [Java::java.lang.String.java_class]).call(key))
      end
      raise ArgumentError, "Invalid arguments when calling get(key)"
    end

### - (`Fixnum`) get_instance_count

@return the number of instances of the verticle that were deployed in the deployment (if any) related to this context

Returns:

- (`Fixnum`)

Raises:

- (`ArgumentError`)

    206
    207
    208
    209
    210
    211
    # File '/Users/julien/java/vertx-stack/stack-docs/target/rb/vertx/context.rb', line 206

    def get_instance_count
      if !block_given?
        return @j_del.java_method(:getInstanceCount, []).call()
      end
      raise ArgumentError, "Invalid arguments when calling get_instance_count()"
    end

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

Is the current context a multi-threaded worker context?

Returns:

- (`true`, `false`) —
  true if the current context is a multi-threaded worker context, false otherwise

Raises:

- (`ArgumentError`)

    159
    160
    161
    162
    163
    164
    # File '/Users/julien/java/vertx-stack/stack-docs/target/rb/vertx/context.rb', line 159

    def multi_threaded_worker_context?
      if !block_given?
        return @j_del.java_method(:isMultiThreadedWorkerContext, []).call()
      end
      raise ArgumentError, "Invalid arguments when calling multi_threaded_worker_context?()"
    end

### - (`::Vertx::Vertx`) owner

@return The Vertx instance that created the context

Returns:

- (`::Vertx::Vertx`)

Raises:

- (`ArgumentError`)

    197
    198
    199
    200
    201
    202
    # File '/Users/julien/java/vertx-stack/stack-docs/target/rb/vertx/context.rb', line 197

    def owner
      if !block_given?
        return ::Vertx::Util::Utils.safe_create(@j_del.java_method(:owner, []).call(),::Vertx::Vertx)
      end
      raise ArgumentError, "Invalid arguments when calling owner()"
    end

### - (`Array<String>`) process_args

The process args

Returns:

- (`Array<String>`)

Raises:

- (`ArgumentError`)

    127
    128
    129
    130
    131
    132
    # File '/Users/julien/java/vertx-stack/stack-docs/target/rb/vertx/context.rb', line 127

    def process_args
      if !block_given?
        return @j_del.java_method(:processArgs, []).call().to_a.map { |elt| elt }
      end
      raise ArgumentError, "Invalid arguments when calling process_args()"
    end

### - (`void`) put(key = nil, value = nil)

This method returns an undefined value.

Put some data in the context.

This can be used to share data between different handlers that share a context

Parameters:

- key (`String`) (defaults to: `nil`) —
  the key of the data
- value (`Object`) (defaults to: `nil`) —
  the data

Raises:

- (`ArgumentError`)

    180
    181
    182
    183
    184
    185
    # File '/Users/julien/java/vertx-stack/stack-docs/target/rb/vertx/context.rb', line 180

    def put(key=nil,value=nil)
      if key.class == String && (value.class == String  || value.class == Hash || value.class == Array || value.class == NilClass || value.class == TrueClass || value.class == FalseClass || value.class == Fixnum || value.class == Float) && !block_given?
        return @j_del.java_method(:put, [Java::java.lang.String.java_class,Java::java.lang.Object.java_class]).call(key,::Vertx::Util::Utils.to_object(value))
      end
      raise ArgumentError, "Invalid arguments when calling put(key,value)"
    end

### - (`true`, `false`) remove?(key = nil)

Remove some data from the context.

Parameters:

- key (`String`) (defaults to: `nil`) —
  the key to remove

Returns:

- (`true`, `false`) —
  true if removed successfully, false otherwise

Raises:

- (`ArgumentError`)

    189
    190
    191
    192
    193
    194
    # File '/Users/julien/java/vertx-stack/stack-docs/target/rb/vertx/context.rb', line 189

    def remove?(key=nil)
      if key.class == String && !block_given?
        return @j_del.java_method(:remove, [Java::java.lang.String.java_class]).call(key)
      end
      raise ArgumentError, "Invalid arguments when calling remove?(key)"
    end

### - (`void`) run_on_context { ... }

This method returns an undefined value.

Run the specified action asynchronously on the same context, some time after the current execution has completed.

Yields:

- the action to run

Raises:

- (`ArgumentError`)

    80
    81
    82
    83
    84
    85
    # File '/Users/julien/java/vertx-stack/stack-docs/target/rb/vertx/context.rb', line 80

    def run_on_context
      if block_given?
        return @j_del.java_method(:runOnContext, [Java::IoVertxCore::Handler.java_class]).call(Proc.new { yield })
      end
      raise ArgumentError, "Invalid arguments when calling run_on_context()"
    end

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

Is the current context a worker context?

NOTE! when running blocking code using Vertx#execute_blocking from a standard (not worker) verticle, the context will still an event loop context and this will return false.

Returns:

- (`true`, `false`) —
  true if the current context is a worker context, false otherwise

Raises:

- (`ArgumentError`)

    151
    152
    153
    154
    155
    156
    # File '/Users/julien/java/vertx-stack/stack-docs/target/rb/vertx/context.rb', line 151

    def worker_context?
      if !block_given?
        return @j_del.java_method(:isWorkerContext, []).call()
      end
      raise ArgumentError, "Invalid arguments when calling worker_context?()"
    end