Module: Garcon

Included in:
Chef::Provider::Archive, Chef::Provider::Civilize, Chef::Provider::Development, Chef::Provider::Download, Chef::Provider::HouseKeeping, Chef::Provider::Partial, Chef::Provider::ZipFile, Chef::Resource::Archive, Chef::Resource::Civilize, Chef::Resource::Development, Chef::Resource::Download, Chef::Resource::HouseKeeping, Chef::Resource::Partial, Chef::Resource::ZipFile
Defined in:
lib/garcon/version.rb,
lib/garcon.rb,
lib/garcon/secret.rb,
lib/garcon/task/ivar.rb,
lib/garcon/exceptions.rb,
lib/garcon/task/delay.rb,
lib/garcon/task/event.rb,
lib/garcon/task/timer.rb,
lib/garcon/inflections.rb,
lib/garcon/stash/queue.rb,
lib/garcon/stash/store.rb,
lib/garcon/task/atomic.rb,
lib/garcon/task/future.rb,
lib/garcon/stash/format.rb,
lib/garcon/utility/misc.rb,
lib/garcon/configuration.rb,
lib/garcon/stash/journal.rb,
lib/garcon/task/executor.rb,
lib/garcon/utility/retry.rb,
lib/garcon/task/condition.rb,
lib/garcon/task/timer_set.rb,
lib/garcon/utility/crypto.rb,
lib/garcon/chef/secret_bag.rb,
lib/garcon/chef_inclusions.rb,
lib/garcon/task/obligation.rb,
lib/garcon/task/observable.rb,
lib/garcon/task/timer_task.rb,
lib/garcon/utility/hookers.rb,
lib/garcon/utility/timeout.rb,
lib/garcon/chef/validations.rb,
lib/garcon/stash/serializer.rb,
lib/garcon/utility/memstash.rb,
lib/garcon/chef/chef_helpers.rb,
lib/garcon/core_ext/pathname.rb,
lib/garcon/utility/at_random.rb,
lib/garcon/task/waitable_list.rb,
lib/garcon/utility/url_helper.rb,
lib/garcon/chef/coerce/coercer.rb,
lib/garcon/chef/coerce/coercer.rb,
lib/garcon/task/atomic_boolean.rb,
lib/garcon/task/lazy_reference.rb,
lib/garcon/task/monotonic_time.rb,
lib/garcon/task/priority_queue.rb,
lib/garcon/utility/file_helper.rb,
lib/garcon/task/dereferenceable.rb,
lib/garcon/task/processor_count.rb,
lib/garcon/task/read_write_lock.rb,
lib/garcon/chef/resource/blender.rb,
lib/garcon/task/count_down_latch.rb,
lib/garcon/task/executor_options.rb,
lib/garcon/utility/interpolation.rb,
lib/garcon/chef/provider/recovery.rb,
lib/garcon/chef/resource/base_dsl.rb,
lib/garcon/core_ext/method_access.rb,
lib/garcon/task/thread_pool/fixed.rb,
lib/garcon/chef/resource/attribute.rb,
lib/garcon/chef/resource/lazy_eval.rb,
lib/garcon/inflections/inflections.rb,
lib/garcon/task/immediate_executor.rb,
lib/garcon/task/safe_task_executor.rb,
lib/garcon/task/thread_pool/cached.rb,
lib/garcon/task/thread_pool/worker.rb,
lib/garcon/task/thread_pool/executor.rb,
lib/garcon/task/single_thread_executor.rb,
lib/garcon/inflections/rules_collection.rb,
lib/garcon/task/copy_on_write_observer_set.rb,
lib/garcon/task/copy_on_notify_observer_set.rb,
lib/garcon/chef/coerce/coercions/date_definitions.rb,
lib/garcon/chef/coerce/coercions/hash_definitions.rb,
lib/garcon/chef/coerce/coercions/time_definitions.rb,
lib/garcon/chef/coerce/coercions/float_definitions.rb,
lib/garcon/chef/coerce/coercions/fixnum_definitions.rb,
lib/garcon/chef/coerce/coercions/string_definitions.rb,
lib/garcon/chef/coerce/coercions/boolean_definitions.rb,
lib/garcon/chef/coerce/coercions/integer_definitions.rb,
lib/garcon/chef/coerce/coercions/date_time_definitions.rb

Overview

Author: Stefano Harding <[email protected]> License: Apache License, Version 2.0 Copyright: © 2014-2015 Stefano Harding

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Defined Under Namespace

Modules: AtRandom, AtomicDirectUpdate, AtomicNumericCompareAndSetWrapper, ChefHelpers, Coercions, Crypto, Dereferenceable, Exceptions, Executor, ExecutorOptions, Extensions, FileHelper, Hacker, Hookers, Inflections, Interpolation, Names, Obligation, Observable, Pathref, Provider, Recovery, Resource, Retry, RubyExecutor, Secret, SecretBag, SerialExecutor, Stash, Timeout, UrlHelper, Version Classes: AtomicBoolean, AtomicMutex, CachedThreadPool, Coercer, Coercion, Condition, Configuration, CopyOnNotifyObserverSet, CopyOnWriteObserverSet, CountDownLatch, Delay, Event, FixedThreadPool, Future, IVar, ImmediateExecutor, LazyReference, MemStash, MutexAtomicBoolean, MutexCountDownLatch, MutexPriorityQueue, PriorityQueue, ProcessorCounter, ReadWriteLock, RubySingleThreadExecutor, SafeTaskExecutor, StashCache, ThreadPoolExecutor, TimerSet, TimerTask, WaitableList

Constant Summary collapse

VERSION = 
Garcon::Version.string

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.auto_terminate_all_executors? ⇒ Boolean

Returns true when all thread pools will auto-terminate on application exit using an ‘at_exit` handler; false when no auto-termination will occur.

Returns:

  • (Boolean) —

    true when all thread pools will auto-terminate on application exit using an ‘at_exit` handler; false when no auto-termination will occur.



195
196
197
 
# File 'lib/garcon.rb', line 195

def self.auto_terminate_all_executors?
  Garcon.config.auto_terminate_all_executors.value
end

.auto_terminate_global_executors? ⇒ Boolean

Returns true when global thread pools will auto-terminate on application exit using an ‘at_exit` handler; false when no auto-termination will occur.

Returns:

  • (Boolean) —

    true when global thread pools will auto-terminate on application exit using an ‘at_exit` handler; false when no auto-termination will occur.



178
179
180
 
# File 'lib/garcon.rb', line 178

def self.auto_terminate_global_executors?
  Garcon.config.auto_terminate_global_executors.value
end

.coercer ⇒ Object 



21
22
23
24
25
26
 
# File 'lib/garcon/chef/coerce/coercer.rb', line 21

def self.coercer
  return @coercer if @coercer
  @coercer = Garcon::Coercer.new
  Garcon::Coercions.bind_to(@coercer)
  @coercer
end

.coercer=(coercer) ⇒ Object 



28
29
30
 
# File 'lib/garcon/chef/coerce/coercer.rb', line 28

def self.coercer=(coercer)
  @coercer = coercer
end

.config {|configuration| ... } ⇒ Configuration

Provides access to the global Garcon configuration

Examples:

Garcon.config do |config|
  config.blender = true
end

Yields:

Returns:



151
152
153
154
 
# File 'lib/garcon.rb', line 151

def self.config(&block)
  yield configuration if block_given?
  configuration
end

.configuration ⇒ Configuration

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Global configuration instance.

Returns:



161
162
163
 
# File 'lib/garcon.rb', line 161

def self.configuration
  @configuration ||= Configuration.new
end

.crypto ⇒ Boolean

Returns the global Crypto setting.

Returns:



86
87
88
 
# File 'lib/garcon.rb', line 86

def self.crypto(&block)
  configuration.crypto(&block)
end

.crypto=(value) ⇒ Garcon::Crypto

Sets the global Crypto configuration value.

Parameters:

Returns:



97
98
99
100
 
# File 'lib/garcon.rb', line 97

def self.crypto=(value)
  configuration.crypto = value
  self
end

.disable_auto_termination_of_all_executors! ⇒ Object

Defines if ALL executors should be auto-terminated with an ‘at_exit` callback. When set to `false` it will be the application programmer’s responsibility to ensure that all thread pools, including the global thread pools, are shutdown properly prior to application exit.



187
188
189
 
# File 'lib/garcon.rb', line 187

def self.disable_auto_termination_of_all_executors!
  Garcon.config.auto_terminate_all_executors.make_false
end

.disable_auto_termination_of_global_executors! ⇒ Object

Defines if global executors should be auto-terminated with an ‘at_exit` callback. When set to `false` it will be the application programmer’s responsibility to ensure that the global thread pools are shutdown properly prior to application exit.



170
171
172
 
# File 'lib/garcon.rb', line 170

def self.disable_auto_termination_of_global_executors!
  Garcon.config.auto_terminate_global_executors.make_false
end

.global_fast_executor ⇒ ThreadPoolExecutor

Global thread pool optimized for short, fast operations.

Returns:



202
203
204
 
# File 'lib/garcon.rb', line 202

def self.global_fast_executor
  Garcon.config.global_fast_executor.value
end

.global_io_executor ⇒ ThreadPoolExecutor

Global thread pool optimized for long, blocking (IO) tasks.

Returns:



209
210
211
 
# File 'lib/garcon.rb', line 209

def self.global_io_executor
  Garcon.config.global_io_executor.value
end

.global_timer_set ⇒ Garcon::TimerSet

Global thread pool user for global timers.

Returns:

See Also:

  • timer


218
219
220
 
# File 'lib/garcon.rb', line 218

def self.global_timer_set
  Garcon.config.global_timer_set.value
end

.included(descendant) ⇒ self

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Hook called when module is included, extends a descendant with class and instance methods.

Parameters:

  • descendant (Module) —

    the module or class including Garcon

Returns:

  • (self) 


51
52
53
54
55
56
57
58
 
# File 'lib/garcon.rb', line 51

def self.included(object)
  super
  if Class === object
    object.send(:include, ClassInclusions)
  else
    object.extend(ModuleExtensions)
  end
end

.kill_global_executors ⇒ Object 



228
229
230
231
232
 
# File 'lib/garcon.rb', line 228

def self.kill_global_executors
  global_fast_executor.kill
  global_io_executor.kill
  global_timer_set.kill
end

.monotonic_time ⇒ Float

Returns the current time a tracked by the application monotonic clock.

Returns:

  • (Float) —

    The current monotonic time when ‘since` not given else the elapsed monotonic time between `since` and the current time



65
66
67
 
# File 'lib/garcon/task/monotonic_time.rb', line 65

def monotonic_time
  GLOBAL_MONOTONIC_CLOCK.get_time
end

.new_fast_executor(opts = {}) ⇒ Object 



242
243
244
245
246
247
248
249
250
 
# File 'lib/garcon.rb', line 242

def self.new_fast_executor(opts = {})
  FixedThreadPool.new(
    [2, Garcon.processor_count].max,
    stop_on_exit:     opts.fetch(:stop_on_exit, true),
    idletime:         60,         # 1 minute
    max_queue:        0,          # unlimited
    fallback_policy: :caller_runs # shouldn't matter -- 0 max queue
  )
end

.new_io_executor(opts = {}) ⇒ Object 



252
253
254
255
256
257
258
259
260
261
 
# File 'lib/garcon.rb', line 252

def self.new_io_executor(opts = {})
  ThreadPoolExecutor.new(
    min_threads:      [2, Garcon.processor_count].max,
    max_threads:      ThreadPoolExecutor::DEFAULT_MAX_POOL_SIZE,
    stop_on_exit:     opts.fetch(:stop_on_exit, true),
    idletime:         60,         # 1 minute
    max_queue:        0,          # unlimited
    fallback_policy: :caller_runs # shouldn't matter -- 0 max queue
  )
end

.physical_processor_count ⇒ Object 



125
126
127
 
# File 'lib/garcon/task/processor_count.rb', line 125

def self.physical_processor_count
  processor_counter.physical_processor_count
end

.processor_count ⇒ Object 



121
122
123
 
# File 'lib/garcon/task/processor_count.rb', line 121

def self.processor_count
  processor_counter.processor_count
end

.secret ⇒ Boolean

Returns the global Secret setting.

Returns:



116
117
118
 
# File 'lib/garcon.rb', line 116

def self.secret(&block)
  configuration.secret(&block)
end

.secret=(value) ⇒ Garcon::Secret

Sets the global Secret configuration value.

Parameters:

Returns:



127
128
129
130
 
# File 'lib/garcon.rb', line 127

def self.secret=(value)
  configuration.secret = value
  self
end

.shutdown_global_executors ⇒ Object 



222
223
224
225
226
 
# File 'lib/garcon.rb', line 222

def self.shutdown_global_executors
  global_fast_executor.shutdown
  global_io_executor.shutdown
  global_timer_set.shutdown
end

.timer(seconds, *args) { ... } ⇒ Boolean

Perform the given operation asynchronously after the given number of seconds.

Parameters:

  • seconds (Fixnum) —

    The interval in seconds to wait before executing the task

Yields:

  • the task to execute

Returns:

Raises:

  • (ArgumentError) 


34
35
36
37
38
39
40
41
42
 
# File 'lib/garcon/task/timer.rb', line 34

def timer(seconds, *args, &block)
  raise ArgumentError, 'no block given' unless block_given?
  if seconds < 0
    raise ArgumentError, 'interval must be greater than or equal to zero'
  end

  Garcon.global_timer_set.post(seconds, *args, &block)
  true
end

.wait_for_global_executors_termination(timeout = nil) ⇒ Object 



234
235
236
237
238
239
240
 
# File 'lib/garcon.rb', line 234

def self.wait_for_global_executors_termination(timeout = nil)
  latch = CountDownLatch.new(3)
  [ global_fast_executor, global_io_executor, global_timer_set ].each do |ex|
    Thread.new { ex.wait_for_termination(timeout); latch.count_down }
  end
  latch.wait(timeout)
end

.warn(msg) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



282
283
284
 
# File 'lib/garcon.rb', line 282

def self.warn(msg)
  Kernel.warn(msg)
end

Instance Method Details

#inspect ⇒ String

Returns object inspection.

Returns:

  • (String) —

    object inspection



265
266
267
268
269
270
271
272
273
 
# File 'lib/garcon.rb', line 265

def inspect
  instance_variables.inject([
    "\n#<#{self.class}:0x#{object_id.to_s(16)}>",
    "\tInstance variables:"
  ]) do |result, item|
    result << "\t\t#{item} = #{instance_variable_get(item)}"
    result
  end.join("\n")
end

#terminal_dimensions ⇒ Integer

Returns the columns and lines of the current tty.

Returns:

  • (Integer) —

    Number of columns and lines of tty, returns [0, 0] if no tty is present.



26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
 
# File 'lib/garcon/utility/misc.rb', line 26

def terminal_dimensions
  [0, 0] unless  STDOUT.tty?
  [80, 40] if OS.windows?

  if ENV['COLUMNS'] && ENV['LINES']
    [ENV['COLUMNS'].to_i, ENV['LINES'].to_i]
  elsif ENV['TERM'] && command_in_path?('tput')
    [`tput cols`.to_i, `tput lines`.to_i]
  elsif command_in_path?('stty')
    `stty size`.scan(/\d+/).map {|s| s.to_i }
  else
    [0, 0]
  end
rescue
  [0, 0]
end

#to_s ⇒ String

Returns string of instance.

Returns:

  • (String) —

    string of instance



277
278
279
 
# File 'lib/garcon.rb', line 277

def to_s
  "<#{self.class}:0x#{object_id.to_s(16)}>"
end