ruby-changes:26885
From: drbrain <ko1@a...>
Date: Fri, 25 Jan 2013 12:25:52 +0900 (JST)
Subject: [ruby-changes:26885] drbrain:r38937 (trunk): * lib/drb/drb.rb: Improved documentation by adding or hiding methods.
drbrain 2013-01-25 12:25:39 +0900 (Fri, 25 Jan 2013) New Revision: 38937 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=38937 Log: * 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. Modified files: trunk/ChangeLog trunk/lib/drb/drb.rb trunk/lib/drb/eq.rb trunk/lib/drb/extserv.rb trunk/lib/drb/gw.rb trunk/lib/drb/invokemethod.rb trunk/lib/drb/observer.rb trunk/lib/drb/ssl.rb trunk/lib/drb/timeridconv.rb trunk/lib/drb/unix.rb trunk/sample/drb/gw_cu.rb Index: ChangeLog =================================================================== --- ChangeLog (revision 38936) +++ ChangeLog (revision 38937) @@ -1,3 +1,17 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1 +Fri Jan 25 12:23:29 2013 Eric Hodel <drbrain@s...> + + * 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. + Fri Jan 25 12:01:56 2013 Koichi Sasada <ko1@a...> * vm_core.h: modify a comment about rb_iseq_t::local_size. Index: sample/drb/gw_cu.rb =================================================================== --- sample/drb/gw_cu.rb (revision 38936) +++ sample/drb/gw_cu.rb (revision 38937) @@ -13,7 +13,7 @@ class Foo https://github.com/ruby/ruby/blob/trunk/sample/drb/gw_cu.rb#L13 end end -DRb.start_service('drubyunix:', nil) +DRb.start_service('drbunix:', nil) puts DRb.uri ro = DRbObject.new(nil, ARGV.shift) Index: lib/drb/gw.rb =================================================================== --- lib/drb/gw.rb (revision 38936) +++ lib/drb/gw.rb (revision 38937) @@ -2,8 +2,36 @@ require 'drb/drb' https://github.com/ruby/ruby/blob/trunk/lib/drb/gw.rb#L2 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 https://github.com/ruby/ruby/blob/trunk/lib/drb/gw.rb#L39 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 https://github.com/ruby/ruby/blob/trunk/lib/drb/gw.rb#L69 end end - class DRbObject + class DRbObject # :nodoc: def self._load(s) uri, ref = Marshal.load(s) if DRb.uri == uri Index: lib/drb/extserv.rb =================================================================== --- lib/drb/extserv.rb (revision 38936) +++ lib/drb/extserv.rb (revision 38937) @@ -42,6 +42,8 @@ module DRb https://github.com/ruby/ruby/blob/trunk/lib/drb/extserv.rb#L42 end end +# :stopdoc: + if __FILE__ == $0 class Foo include DRbUndumped Index: lib/drb/ssl.rb =================================================================== --- lib/drb/ssl.rb (revision 38936) +++ lib/drb/ssl.rb (revision 38937) @@ -5,8 +5,13 @@ require 'singleton' https://github.com/ruby/ruby/blob/trunk/lib/drb/ssl.rb#L5 module DRb + # The protocol for DRb over an SSL socket + # + # The URI for a DRb socket over SSL is: + # <code>drbssl://<host>:<port>?<option></code>. The option is optional class DRbSSLSocket < DRbTCPSocket + # :stopdoc: class SSLConfig DEFAULT = { @@ -190,6 +195,8 @@ module DRb https://github.com/ruby/ruby/blob/trunk/lib/drb/ssl.rb#L195 retry end end + + # :stopdoc: end DRbProtocol.add_protocol(DRbSSLSocket) Index: lib/drb/timeridconv.rb =================================================================== --- lib/drb/timeridconv.rb (revision 38936) +++ lib/drb/timeridconv.rb (revision 38937) @@ -2,8 +2,17 @@ require 'drb/drb' https://github.com/ruby/ruby/blob/trunk/lib/drb/timeridconv.rb#L2 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 https://github.com/ruby/ruby/blob/trunk/lib/drb/timeridconv.rb#L80 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 Index: lib/drb/unix.rb =================================================================== --- lib/drb/unix.rb (revision 38936) +++ lib/drb/unix.rb (revision 38937) @@ -6,7 +6,13 @@ raise(LoadError, "UNIXServer is required https://github.com/ruby/ruby/blob/trunk/lib/drb/unix.rb#L6 module DRb + # Implements DRb over a UNIX socket + # + # DRb UNIX socket URIs look like <code>drbunix:<path>?<option></code>. The + # option is optional. + class DRbUNIXSocket < DRbTCPSocket + # :stopdoc: def self.parse_uri(uri) if /^drbunix:(.*?)(\?(.*))?$/ =~ uri filename = $1 @@ -105,4 +111,5 @@ module DRb https://github.com/ruby/ruby/blob/trunk/lib/drb/unix.rb#L111 end DRbProtocol.add_protocol(DRbUNIXSocket) + # :startdoc: end Index: lib/drb/eq.rb =================================================================== --- lib/drb/eq.rb (revision 38936) +++ lib/drb/eq.rb (revision 38937) @@ -1,5 +1,5 @@ https://github.com/ruby/ruby/blob/trunk/lib/drb/eq.rb#L1 module DRb - class DRbObject + class DRbObject # :nodoc: def ==(other) return false unless DRbObject === other (@ref == other.__drbref) && (@uri == other.__drburi) Index: lib/drb/drb.rb =================================================================== --- lib/drb/drb.rb (revision 38936) +++ lib/drb/drb.rb (revision 38937) @@ -426,6 +426,8 @@ module DRb https://github.com/ruby/ruby/blob/trunk/lib/drb/drb.rb#L426 # 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 https://github.com/ruby/ruby/blob/trunk/lib/drb/drb.rb#L507 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 https://github.com/ruby/ruby/blob/trunk/lib/drb/drb.rb#L532 } 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 https://github.com/ruby/ruby/blob/trunk/lib/drb/drb.rb#L640 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 https://github.com/ruby/ruby/blob/trunk/lib/drb/drb.rb#L804 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: + # <code>druby://<host>:<port>?<option></code>. The option is optional. + class DRbTCPSocket + # :stopdoc: private def self.parse_uri(uri) if uri =~ /^druby:\/\/(.*?):(\d+)(\?(.*))?$/ @@ -840,6 +854,7 @@ module DRb https://github.com/ruby/ruby/blob/trunk/lib/drb/drb.rb#L854 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 https://github.com/ruby/ruby/blob/trunk/lib/drb/drb.rb#L1023 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 https://github.com/ruby/ruby/blob/trunk/lib/drb/drb.rb#L1075 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 https://github.com/ruby/ruby/blob/trunk/lib/drb/drb.rb#L1087 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 https://github.com/ruby/ruby/blob/trunk/lib/drb/drb.rb#L1112 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 https://github.com/ruby/ruby/blob/trunk/lib/drb/drb.rb#L1123 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 https://github.com/ruby/ruby/blob/trunk/lib/drb/drb.rb#L1268 @@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 https://github.com/ruby/ruby/blob/trunk/lib/drb/drb.rb#L1385 # 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 https://github.com/ruby/ruby/blob/trunk/lib/drb/drb.rb#L1403 @thread.alive? end + # Is +uri+ the URI for this server? def here?(uri) @exported_uri.include?(uri) end @@ -1737,12 +1758,15 @@ module DRb https://github.com/ruby/ruby/blob/trunk/lib/drb/drb.rb#L1758 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 https://github.com/ruby/ruby/blob/trunk/lib/drb/drb.rb#L1775 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 Index: lib/drb/observer.rb =================================================================== --- lib/drb/observer.rb (revision 38936) +++ lib/drb/observer.rb (revision 38937) @@ -1,9 +1,12 @@ https://github.com/ruby/ruby/blob/trunk/lib/drb/observer.rb#L1 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 Index: lib/drb/invokemethod.rb =================================================================== --- lib/drb/invokemethod.rb (revision 38936) +++ lib/drb/invokemethod.rb (revision 38937) @@ -2,7 +2,7 @@ https://github.com/ruby/ruby/blob/trunk/lib/drb/invokemethod.rb#L2 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]) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/