Module: Mongo::BackgroundThread Private

Includes:
Loggable
Included in:
Cluster::PeriodicExecutor, Server::ConnectionPool::Populator, Server::Monitor, Server::PushMonitor, Srv::Monitor
Defined in:
build/ruby-driver-v2.19/lib/mongo/background_thread.rb

Overview

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

Note:

Do not start or stop background threads in finalizers. See jira.mongodb.org/browse/RUBY-2453 and bugs.ruby-lang.org/issues/16288. When interpreter exits, background threads are stopped first and finalizers are invoked next, and MRI’s internal data structures are basically corrupt at this point if threads are being referenced. Prior to interpreter shutdown this means threads cannot be stopped by objects going out of scope, but most likely the threads hold references to said objects anyway if work is being performed thus the objects wouldn’t go out of scope in the first place.

The run!, running? and stop! methods used to be part of the public API in some of the classes which now include this module. Therefore these methods must be considered part of the driver’s public API for backwards compatibility reasons. However using these methods outside of the driver is deprecated.

Constant Summary

Constants included from Loggable

Loggable::PREFIX

Instance Method Summary collapse

Methods included from Loggable

#log_debug, #log_error, #log_fatal, #log_info, #log_warn, #logger

Instance Method Details

#run! ⇒ Object

Start the background thread.

If the thread is already running, this method does nothing.



46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
 
# File 'build/ruby-driver-v2.19/lib/mongo/background_thread.rb', line 46

def run!
  if @stop_requested && @thread
    wait_for_stop
    if @thread.alive?
      log_warn("Starting a new background thread in #{self}, but the previous background thread is still running")
      @thread = nil
    end
    @stop_requested = false
  end
  if running?
    @thread
  else
    start!
  end
end

#running? ⇒ Boolean

Returns:

  • (Boolean) 


63
64
65
66
67
68
69
 
# File 'build/ruby-driver-v2.19/lib/mongo/background_thread.rb', line 63

def running?
  if @thread
    @thread.alive?
  else
    false
  end
end

#stop! ⇒ true | false

Stop the background thread and wait for to terminate for a reasonable amount of time.

Returns:

  • (true | false) —

    Whether the thread was terminated.



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
 
# File 'build/ruby-driver-v2.19/lib/mongo/background_thread.rb', line 77

def stop!
  # If the thread was not started, there is nothing to stop.
  #
  # Classes including this module may want to perform additional
  # cleanup, which they can do by overriding this method.
  return true unless @thread

  # Background threads generally perform operations in a loop.
  # This flag is meant to be checked on each iteration of the
  # working loops and the thread should stop working when this flag
  # is set.
  @stop_requested = true

  # Besides setting the flag, a particular class may have additional
  # ways of signaling the background thread to either stop working or
  # wake up to check the stop flag, for example, setting a semaphore.
  # This can be accomplished by providing the pre_stop method.
  pre_stop

  # Now we have requested the graceful termination, and we could wait
  # for the thread to exit on its own accord. A future version of the
  # driver may allow a certain amount of time for the thread to quit.
  # For now, we additionally use the Ruby machinery to request the thread
  # be terminated, and do so immediately.
  #
  # Note that this may cause the background thread to terminate in
  # the middle of an operation.
  @thread.kill

  wait_for_stop
end