summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authordrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2013-01-25 03:25:39 +0000
committerdrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2013-01-25 03:25:39 +0000
commit90e69dfdaf0b603f3adef052274a4a73bde6e901 (patch)
tree3d2f574f9d0e5dceb08057ebea985f3857c807b9
parentd50bd4939a79bb53aeaf8c607e3d6612d3167022 (diff)
* 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
-rw-r--r--ChangeLog14
-rw-r--r--lib/drb/drb.rb44
-rw-r--r--lib/drb/eq.rb2
-rw-r--r--lib/drb/extserv.rb2
-rw-r--r--lib/drb/gw.rb42
-rw-r--r--lib/drb/invokemethod.rb2
-rw-r--r--lib/drb/observer.rb3
-rw-r--r--lib/drb/ssl.rb7
-rw-r--r--lib/drb/timeridconv.rb16
-rw-r--r--lib/drb/unix.rb7
-rw-r--r--sample/drb/gw_cu.rb2
11 files changed, 124 insertions, 17 deletions
diff --git a/ChangeLog b/ChangeLog
index 6eec9e4..2b8cd99 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,17 @@
+Fri Jan 25 12:23:29 2013 Eric Hodel <drbrain@segment7.net>
+
+ * 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@atdot.net>
* vm_core.h: modify a comment about rb_iseq_t::local_size.
diff --git a/lib/drb/drb.rb b/lib/drb/drb.rb
index fa914f8..f5d4a26 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:
+ # <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
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 6328c81..553f30c 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 bb11211..c70ced8 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 b7a5f53..b3568ab 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 353dbd0..d11feab 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 149426d..cab9ebc 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 c4f7698..c0dd9c4 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:
+ # <code>drbssl://<host>:<port>?<option></code>. 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 b460e2c..4ea3035 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 6de5052..4d24578 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 <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
end
DRbProtocol.add_protocol(DRbUNIXSocket)
+ # :startdoc:
end
diff --git a/sample/drb/gw_cu.rb b/sample/drb/gw_cu.rb
index 0e5ed36..8079cbd 100644
--- a/sample/drb/gw_cu.rb
+++ b/sample/drb/gw_cu.rb
@@ -13,7 +13,7 @@ class Foo
end
end
-DRb.start_service('drubyunix:', nil)
+DRb.start_service('drbunix:', nil)
puts DRb.uri
ro = DRbObject.new(nil, ARGV.shift)