From 90e69dfdaf0b603f3adef052274a4a73bde6e901 Mon Sep 17 00:00:00 2001 From: drbrain Date: Fri, 25 Jan 2013 03:25:39 +0000 Subject: * lib/drb/drb.rb: Improved documentation by adding or hiding methods. * lib/drb/eq.rb: ditto. * lib/drb/extserv.rb: ditto. * lib/drb/gw.rb: ditto. * lib/drb/invokemethod.rb: ditto. * lib/drb/observer.rb: ditto. * lib/drb/ssl.rb: ditto. * lib/drb/timeridconv.rb: ditto. * lib/drb/unix.rb: ditto. * sample/drb/gw_cu.rb: Fixed bug in DRb gateway sample. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@38937 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- lib/drb/drb.rb | 44 +++++++++++++++++++++++++++++++++++--------- lib/drb/eq.rb | 2 +- lib/drb/extserv.rb | 2 ++ lib/drb/gw.rb | 42 ++++++++++++++++++++++++++++++++++++++++-- lib/drb/invokemethod.rb | 2 +- lib/drb/observer.rb | 3 +++ lib/drb/ssl.rb | 7 +++++++ lib/drb/timeridconv.rb | 16 +++++++++++++--- lib/drb/unix.rb | 7 +++++++ 9 files changed, 109 insertions(+), 16 deletions(-) (limited to 'lib') diff --git a/lib/drb/drb.rb b/lib/drb/drb.rb index fa914f877d..f5d4a26906 100644 --- a/lib/drb/drb.rb +++ b/lib/drb/drb.rb @@ -426,6 +426,8 @@ module DRb # An exception wrapping an error object class DRbRemoteError < DRbError + + # Creates a new remote error that wraps the Exception +error+ def initialize(error) @reason = error.class.to_s super("#{error.message} (#{error.class})") @@ -505,7 +507,16 @@ module DRb end end + # An Array wrapper that can be sent to another server via DRb. + # + # All entries in the array will be dumped or be references that point to + # the local server. + class DRbArray + + # Creates a new DRbArray that either dumps or wraps all the items in +ary+ + # so they can be loaded by a remote DRb server. + def initialize(ary) @ary = ary.collect { |obj| if obj.kind_of? DRbUndumped @@ -521,11 +532,11 @@ module DRb } end - def self._load(s) + def self._load(s) # :nodoc: Marshal::load(s) end - def _dump(lv) + def _dump(lv) # :nodoc: Marshal.dump(@ary) end end @@ -629,7 +640,7 @@ module DRb end private - def make_proxy(obj, error=false) + def make_proxy(obj, error=false) # :nodoc: if error DRbRemoteError.new(obj) else @@ -793,10 +804,13 @@ module DRb module_function :auto_load end - # The default drb protocol. + # The default drb protocol which communicates over a TCP socket. # - # Communicates over a TCP socket. + # The DRb TCP protocol URI looks like: + # druby://:?. The option is optional. + class DRbTCPSocket + # :stopdoc: private def self.parse_uri(uri) if uri =~ /^druby:\/\/(.*?):(\d+)(\?(.*))?$/ @@ -840,6 +854,7 @@ module DRb return TCPServer.open('0.0.0.0', port) if families.has_key?('AF_INET') return TCPServer.open('::', port) if families.has_key?('AF_INET6') return TCPServer.open(port) + # :stopdoc: end # Open a server listening for connections at +uri+ using @@ -1008,6 +1023,8 @@ module DRb self.new_with(uri, ref) end + # Creates a new DRbObject from a +uri+ and object +ref+. + def self.new_with(uri, ref) it = self.allocate it.instance_variable_set(:@uri, uri) @@ -1058,6 +1075,7 @@ module DRb undef :to_s undef :to_a if respond_to?(:to_a) + # Routes respond_to? to the referenced remote object. def respond_to?(msg_id, priv=false) case msg_id when :_dump @@ -1069,7 +1087,7 @@ module DRb end end - # Routes method calls to the referenced object. + # Routes method calls to the referenced remote object. def method_missing(msg_id, *a, &b) if DRb.here?(@uri) obj = DRb.to_obj(@ref) @@ -1094,7 +1112,7 @@ module DRb end end - def self.with_friend(uri) + def self.with_friend(uri) # :nodoc: friend = DRb.fetch_server(uri) return yield() unless friend @@ -1105,7 +1123,7 @@ module DRb Thread.current['DRb'] = save if friend end - def self.prepare_backtrace(uri, result) + def self.prepare_backtrace(uri, result) # :nodoc: prefix = "(#{uri}) " bt = [] result.backtrace.each do |x| @@ -1250,6 +1268,7 @@ module DRb @@idconv = idconv end + # Set the default safe level to +level+ def self.default_safe_level(level) @@safe_level = level end @@ -1366,6 +1385,7 @@ module DRb # The configuration of this DRbServer attr_reader :config + # The safe level for this server attr_reader :safe_level # Set whether to operate in verbose mode. @@ -1383,6 +1403,7 @@ module DRb @thread.alive? end + # Is +uri+ the URI for this server? def here?(uri) @exported_uri.include?(uri) end @@ -1737,12 +1758,15 @@ module DRb module_function :install_acl @mutex = Mutex.new - def mutex + def mutex # :nodoc: @mutex end module_function :mutex @server = {} + # Registers +server+ with DRb. + # + # If there is no primary server then +server+ becomes the primary server. def regist_server(server) @server[server.uri] = server mutex.synchronize do @@ -1751,11 +1775,13 @@ module DRb end module_function :regist_server + # Removes +server+ from the list of servers. def remove_server(server) @server.delete(server.uri) end module_function :remove_server + # Retrieves the server with the given +uri+. def fetch_server(uri) @server[uri] end diff --git a/lib/drb/eq.rb b/lib/drb/eq.rb index 6328c81202..553f30c598 100644 --- a/lib/drb/eq.rb +++ b/lib/drb/eq.rb @@ -1,5 +1,5 @@ module DRb - class DRbObject + class DRbObject # :nodoc: def ==(other) return false unless DRbObject === other (@ref == other.__drbref) && (@uri == other.__drburi) diff --git a/lib/drb/extserv.rb b/lib/drb/extserv.rb index bb11211cd1..c70ced877c 100644 --- a/lib/drb/extserv.rb +++ b/lib/drb/extserv.rb @@ -42,6 +42,8 @@ module DRb end end +# :stopdoc: + if __FILE__ == $0 class Foo include DRbUndumped diff --git a/lib/drb/gw.rb b/lib/drb/gw.rb index b7a5f5383f..b3568ab08d 100644 --- a/lib/drb/gw.rb +++ b/lib/drb/gw.rb @@ -2,8 +2,36 @@ require 'drb/drb' require 'monitor' module DRb + + # Gateway id conversion forms a gateway between different DRb protocols or + # networks. + # + # The gateway needs to install this id conversion and create servers for + # each of the protocols or networks it will be a gateway between. It then + # needs to create a server that attaches to each of these networks. For + # example: + # + # require 'drb/drb' + # require 'drb/unix' + # require 'drb/gw' + # + # DRb.install_id_conv DRb::GWIdConv.new + # gw = DRb::GW.new + # s1 = DRb::DRbServer.new 'drbunix:/path/to/gateway', gw + # s2 = DRb::DRbServer.new 'druby://example:10000', gw + # + # s1.thread.join + # s2.thread.join + # + # Each client must register services with the gateway, for example: + # + # DRb.start_service 'drbunix:', nil # an anonymous server + # gw = DRbObject.new nil, 'drbunix:/path/to/gateway' + # gw[:unix] = some_service + # DRb.thread.join + class GWIdConv < DRbIdConv - def to_obj(ref) + def to_obj(ref) # :nodoc: if Array === ref && ref[0] == :DRbObject return DRbObject.new_with(ref[1], ref[2]) end @@ -11,19 +39,29 @@ module DRb end end + # The GW provides a synchronized store for participants in the gateway to + # communicate. + class GW include MonitorMixin + + # Creates a new GW + def initialize super() @hash = {} end + # Retrieves +key+ from the GW + def [](key) synchronize do @hash[key] end end + # Stores value +v+ at +key+ in the GW + def []=(key, v) synchronize do @hash[key] = v @@ -31,7 +69,7 @@ module DRb end end - class DRbObject + class DRbObject # :nodoc: def self._load(s) uri, ref = Marshal.load(s) if DRb.uri == uri diff --git a/lib/drb/invokemethod.rb b/lib/drb/invokemethod.rb index 353dbd00d8..d11feabcb8 100644 --- a/lib/drb/invokemethod.rb +++ b/lib/drb/invokemethod.rb @@ -2,7 +2,7 @@ module DRb class DRbServer - module InvokeMethod18Mixin + module InvokeMethod18Mixin # :nodoc: all def block_yield(x) if x.size == 1 && x[0].class == Array x[0] = DRbArray.new(x[0]) diff --git a/lib/drb/observer.rb b/lib/drb/observer.rb index 149426db7b..cab9ebc60b 100644 --- a/lib/drb/observer.rb +++ b/lib/drb/observer.rb @@ -1,9 +1,12 @@ require 'observer' module DRb + # The Observable module extended to DRb. See Observable for details. module DRbObservable include Observable + # Notifies observers of a change in state. See also + # Observable#notify_observers def notify_observers(*arg) if defined? @observer_state and @observer_state if defined? @observer_peers diff --git a/lib/drb/ssl.rb b/lib/drb/ssl.rb index c4f76987de..c0dd9c49f4 100644 --- a/lib/drb/ssl.rb +++ b/lib/drb/ssl.rb @@ -5,8 +5,13 @@ require 'singleton' module DRb + # The protocol for DRb over an SSL socket + # + # The URI for a DRb socket over SSL is: + # drbssl://:?. The option is optional class DRbSSLSocket < DRbTCPSocket + # :stopdoc: class SSLConfig DEFAULT = { @@ -190,6 +195,8 @@ module DRb retry end end + + # :stopdoc: end DRbProtocol.add_protocol(DRbSSLSocket) diff --git a/lib/drb/timeridconv.rb b/lib/drb/timeridconv.rb index b460e2c987..4ea3035f39 100644 --- a/lib/drb/timeridconv.rb +++ b/lib/drb/timeridconv.rb @@ -2,8 +2,17 @@ require 'drb/drb' require 'monitor' module DRb + + # Timer id conversion keeps objects alive for a certain amount of time after + # their last access. The default time period is 600 seconds and can be + # changed upon initialization. + # + # To use TimerIdConv: + # + # DRb.install_id_conv TimerIdConv.new 60 # one minute + class TimerIdConv < DRbIdConv - class TimerHolder2 + class TimerHolder2 # :nodoc: include MonitorMixin class InvalidIndexError < RuntimeError; end @@ -71,18 +80,19 @@ module DRb end end + # Creates a new TimerIdConv which will hold objects for +timeout+ seconds. def initialize(timeout=600) @holder = TimerHolder2.new(timeout) end - def to_obj(ref) + def to_obj(ref) # :nodoc: return super if ref.nil? @holder.fetch(ref) rescue TimerHolder2::InvalidIndexError raise "invalid reference" end - def to_id(obj) + def to_id(obj) # :nodoc: return @holder.add(obj) end end diff --git a/lib/drb/unix.rb b/lib/drb/unix.rb index 6de5052451..4d245780a5 100644 --- a/lib/drb/unix.rb +++ b/lib/drb/unix.rb @@ -6,7 +6,13 @@ raise(LoadError, "UNIXServer is required") unless defined?(UNIXServer) module DRb + # Implements DRb over a UNIX socket + # + # DRb UNIX socket URIs look like drbunix:?. The + # option is optional. + class DRbUNIXSocket < DRbTCPSocket + # :stopdoc: def self.parse_uri(uri) if /^drbunix:(.*?)(\?(.*))?$/ =~ uri filename = $1 @@ -105,4 +111,5 @@ module DRb end DRbProtocol.add_protocol(DRbUNIXSocket) + # :startdoc: end -- cgit v1.2.3