U:RDoc::NormalModule[iI"DRb:EF@0o:RDoc::Markup::Document:@parts[o;;[ES:RDoc::Markup::Heading:
leveli:	textI"
Overview;To:RDoc::Markup::BlankLineo:RDoc::Markup::Paragraph;[
I"FdRuby is a distributed object system for Ruby.  It is written in ;TI"Ipure Ruby and uses its own protocol.  No add-in services are needed ;TI"Ibeyond those provided by the Ruby runtime, such as TCP sockets.  It ;TI"Ddoes not rely on or interoperate with other distributed object ;TI")systems such as CORBA, RMI, or .NET.;T@o;
;[I"GdRuby allows methods to be called in one Ruby process upon a Ruby ;TI"Fobject located in another Ruby process, even on another machine. ;TI"DReferences to objects can be passed between processes.  Method ;TI"Earguments and return values are dumped and loaded in marshalled ;TI"Jformat.  All of this is done transparently to both the caller of the ;TI"9remote method and the object that it is called upon.;T@o;
;[I"?An object in a remote process is locally represented by a ;TI"DDRb::DRbObject instance.  This acts as a sort of proxy for the ;TI"Eremote object.  Methods called upon this DRbObject instance are ;TI"Jforwarded to its remote object.  This is arranged dynamically at run ;TI"Ctime.  There are no statically declared interfaces for remote ;TI""objects, such as CORBA's IDL.;T@o;
;[
I"EdRuby calls made into a process are handled by a DRb::DRbServer ;TI"Hinstance within that process.  This reconstitutes the method call, ;TI"Jinvokes it upon the specified local object, and returns the value to ;TI"Ithe remote caller.  Any object can receive calls over dRuby.  There ;TI"Cis no need to implement a special interface, or mixin special ;TI"Ffunctionality.  Nor, in the general case, does an object need to ;TI"Eexplicitly register itself with a DRbServer in order to receive ;TI"dRuby calls.;T@o;
;[I"GOne process wishing to make dRuby calls upon another process must ;TI"Dsomehow obtain an initial reference to an object in the remote ;TI"Fprocess by some means other than as the return value of a remote ;TI"Jmethod call, as there is initially no remote object reference it can ;TI"Ginvoke a method upon.  This is done by attaching to the server by ;TI"8URI.  Each DRbServer binds itself to a URI such as ;TI"J'druby://example.com:8787'.  A DRbServer can have an object attached ;TI"Hto it that acts as the server's *front* *object*.  A DRbObject can ;TI"Dbe explicitly created from the server's URI.  This DRbObject's ;TI"Iremote object will be the server's front object.  This front object ;TI"Ican then return references to other Ruby objects in the DRbServer's ;TI"
process.;T@o;
;[
I"IMethod calls made over dRuby behave largely the same as normal Ruby ;TI"Gmethod calls made within a process.  Method calls with blocks are ;TI"Fsupported, as are raising exceptions.  In addition to a method's ;TI"=standard errors, a dRuby call may also raise one of the ;TI"IdRuby-specific errors, all of which are subclasses of DRb::DRbError.;T@o;
;[I"HAny type of object can be passed as an argument to a dRuby call or ;TI"Hreturned as its return value.  By default, such objects are dumped ;TI"Hor marshalled at the local end, then loaded or unmarshalled at the ;TI"Hremote end.  The remote end therefore receives a copy of the local ;TI"Jobject, not a distributed reference to it; methods invoked upon this ;TI"Hcopy are executed entirely in the remote process, not passed on to ;TI"Fthe local original.  This has semantics similar to pass-by-value.;T@o;
;[I"IHowever, if an object cannot be marshalled, a dRuby reference to it ;TI"Iis passed or returned instead.  This will turn up at the remote end ;TI"Jas a DRbObject instance.  All methods invoked upon this remote proxy ;TI"Jare forwarded to the local object, as described in the discussion of ;TI"@DRbObjects.  This has semantics similar to the normal Ruby ;TI"pass-by-reference.;T@o;
;[	I"FThe easiest way to signal that we want an otherwise marshallable ;TI"Fobject to be passed or returned as a DRbObject reference, rather ;TI";than marshalled and sent as a copy, is to include the ;TI"#DRb::DRbUndumped mixin module.;T@o;
;[
I"GdRuby supports calling remote methods with blocks.  As blocks (or ;TI"Hrather the Proc objects that represent them) are not marshallable, ;TI"Ethe block executes in the local, not the remote, context.  Each ;TI"Hvalue yielded to the block is passed from the remote object to the ;TI"Flocal block, then the value returned by each block invocation is ;TI"Ipassed back to the remote execution context to be collected, before ;TI"Gthe collected values are finally returned to the local context as ;TI"/the return value of the method invocation.;T@S;	;
i;I"Examples of usage;T@o;
;[I"EFor more dRuby samples, see the +samples+ directory in the full ;TI"dRuby distribution.;T@S;	;
i;I" dRuby in client/server mode;T@o;
;[I"<This illustrates setting up a simple client-server drb ;TI"Esystem.  Run the server and client code in different terminals, ;TI"$starting the server code first.;T@S;	;
i	;I"Server code;T@o:RDoc::Markup::Verbatim;[I"require 'drb/drb'
;TI"
;TI",# The URI for the server to connect to
;TI""URI="druby://localhost:8787"
;TI"
;TI"class TimeServer
;TI"
;TI"  def get_current_time
;TI"    return Time.now
;TI"  end
;TI"
;TI"	end
;TI"
;TI"6# The object that handles requests on the server
;TI"!FRONT_OBJECT=TimeServer.new
;TI"
;TI".$SAFE = 1   # disable eval() and friends
;TI"
;TI"*DRb.start_service(URI, FRONT_OBJECT)
;TI"@# Wait for the drb server thread to finish before exiting.
;TI"DRb.thread.join
;T:@format0S;	;
i	;I"Client code;T@o;;[I"require 'drb/drb'
;TI"
;TI"# The URI to connect to
;TI")SERVER_URI="druby://localhost:8787"
;TI"
;TI"4# Start a local DRbServer to handle callbacks.
;TI"#
;TI"B# Not necessary for this small example, but will be required
;TI"C# as soon as we pass a non-marshallable object as an argument
;TI"# to a dRuby call.
;TI"#
;TI"O# Note: this must be called at least once per process to take any effect.
;TI"A# This is particularly important if your application forks.
;TI"DRb.start_service
;TI"
;TI"5timeserver = DRbObject.new_with_uri(SERVER_URI)
;TI"&puts timeserver.get_current_time
;T;0S;	;
i;I"Remote objects under dRuby;T@o;
;[
I"AThis example illustrates returning a reference to an object ;TI"Afrom a dRuby call.  The Logger instances live in the server ;TI"Fprocess.  References to them are returned to the client process, ;TI"@where methods can be invoked upon them.  These methods are ;TI"$executed in the server process.;T@S;	;
i	;I"Server code;T@o;;[:I"require 'drb/drb'
;TI"
;TI""URI="druby://localhost:8787"
;TI"
;TI"class Logger
;TI"
;TI"A    # Make dRuby send Logger instances as dRuby references,
;TI"    # not copies.
;TI""    include DRb::DRbUndumped
;TI"
;TI""    def initialize(n, fname)
;TI"        @name = n
;TI"        @filename = fname
;TI"
    end
;TI"
;TI"    def log(message)
;TI".        File.open(@filename, "a") do |f|
;TI"=            f.puts("#{Time.now}: #{@name}: #{message}")
;TI"        end
;TI"
    end
;TI"
;TI"	end
;TI"
;TI"E# We have a central object for creating and retrieving loggers.
;TI"D# This retains a local reference to all loggers created.  This
;TI"C# is so an existing logger can be looked up by name, but also
;TI"A# to prevent loggers from being garbage collected.  A dRuby
;TI"D# reference to an object is not sufficient to prevent it being
;TI"# garbage collected!
;TI"class LoggerFactory
;TI"
;TI"    def initialize(bdir)
;TI"        @basedir = bdir
;TI"        @loggers = {}
;TI"
    end
;TI"
;TI"    def get_logger(name)
;TI"(        if !@loggers.has_key? name
;TI"D            # make the filename safe, then declare it to be so
;TI"=            fname = name.gsub(/[.\/\\\:]/, "_").untaint
;TI"K            @loggers[name] = Logger.new(name, @basedir + "/" + fname)
;TI"        end
;TI"#        return @loggers[name]
;TI"
    end
;TI"
;TI"	end
;TI"
;TI"1FRONT_OBJECT=LoggerFactory.new("/tmp/dlog")
;TI"
;TI".$SAFE = 1   # disable eval() and friends
;TI"
;TI"*DRb.start_service(URI, FRONT_OBJECT)
;TI"DRb.thread.join
;T;0S;	;
i	;I"Client code;T@o;;[I"require 'drb/drb'
;TI"
;TI")SERVER_URI="druby://localhost:8787"
;TI"
;TI"DRb.start_service
;TI"
;TI"4log_service=DRbObject.new_with_uri(SERVER_URI)
;TI"
;TI"0["loga", "logb", "logc"].each do |logname|
;TI"
;TI"0    logger=log_service.get_logger(logname)
;TI"
;TI"%    logger.log("Hello, world!")
;TI"'    logger.log("Goodbye, world!")
;TI"#    logger.log("=== EOT ===")
;TI"
;TI"	end
;T;0S;	;
i;I"
Security;T@o;
;[
I"HAs with all network services, security needs to be considered when ;TI"Iusing dRuby.  By allowing external access to a Ruby object, you are ;TI"Dnot only allowing outside clients to call the methods you have ;TI"Gdefined for that object, but by default to execute arbitrary Ruby ;TI"2code on your server.  Consider the following:;T@o;;[I"# !!! UNSAFE CODE !!!
;TI"Bro = DRbObject::new_with_uri("druby://your.server.com:8989")
;TI"class << ro
;TI"H  undef :instance_eval  # force call to be passed to remote object
;TI"	end
;TI"$ro.instance_eval("`rm -rf *`")
;T;0o;
;[
I"DThe dangers posed by instance_eval and friends are such that a ;TI"BDRbServer should generally be run with $SAFE set to at least ;TI"Elevel 1.  This will disable eval() and related calls on strings ;TI"Hpassed across the wire.  The sample usage code given above follows ;TI"this practice.;T@o;
;[
I"BA DRbServer can be configured with an access control list to ;TI"Hselectively allow or deny access from specified IP addresses.  The ;TI"Jmain druby distribution provides the ACL class for this purpose.  In ;TI"Hgeneral, this mechanism should only be used alongside, rather than ;TI"+as a replacement for, a good firewall.;T@S;	;
i;I"dRuby internals;T@o;
;[
I"GdRuby is implemented using three main components: a remote method ;TI"@call marshaller/unmarshaller; a transport protocol; and an ;TI"IID-to-object mapper.  The latter two can be directly, and the first ;TI"Gindirectly, replaced, in order to provide different behaviour and ;TI"capabilities.;T@o;
;[I"JMarshalling and unmarshalling of remote method calls is performed by ;TI"Ga DRb::DRbMessage instance.  This uses the Marshal module to dump ;TI"Fthe method call before sending it over the transport layer, then ;TI"Ereconstitute it at the other end.  There is normally no need to ;TI"Ereplace this component, and no direct way is provided to do so. ;TI"EHowever, it is possible to implement an alternative marshalling ;TI"@scheme as part of an implementation of the transport layer.;T@o;
;[I"FThe transport layer is responsible for opening client and server ;TI"Cnetwork connections and forwarding dRuby request across them. ;TI"HNormally, it uses DRb::DRbMessage internally to manage marshalling ;TI";and unmarshalling.  The transport layer is managed by ;TI"?DRb::DRbProtocol.  Multiple protocols can be installed in ;TI"JDRbProtocol at the one time; selection between them is determined by ;TI"Cthe scheme of a dRuby URI.  The default transport protocol is ;TI"9selected by the scheme 'druby:', and implemented by ;TI"<DRb::DRbTCPSocket.  This uses plain TCP/IP sockets for ;TI"Icommunication.  An alternative protocol, using UNIX domain sockets, ;TI"Gis implemented by DRb::DRbUNIXSocket in the file drb/unix.rb, and ;TI"Fselected by the scheme 'drbunix:'.  A sample implementation over ;TI"BHTTP can be found in the samples accompanying the main dRuby ;TI"distribution.;T@o;
;[I"EThe ID-to-object mapping component maps dRuby object ids to the ;TI"Gobjects they refer to, and vice versa.  The implementation to use ;TI"Hcan be specified as part of a DRb::DRbServer's configuration.  The ;TI"Gdefault implementation is provided by DRb::DRbIdConv.  It uses an ;TI"Iobject's ObjectSpace id as its dRuby id.  This means that the dRuby ;TI"Jreference to that object only remains meaningful for the lifetime of ;TI"Ethe object's process and the lifetime of the object within that ;TI"Iprocess.  A modified implementation is provided by DRb::TimerIdConv ;TI"Jin the file drb/timeridconv.rb.  This implementation retains a local ;TI"Ereference to all objects exported over dRuby for a configurable ;TI"Gperiod of time (defaulting to ten minutes), to prevent them being ;TI"Hgarbage-collected within this time.  Another sample implementation ;TI"Iis provided in sample/name.rb in the main dRuby distribution.  This ;TI"Jallows objects to specify their own id or "name".  A dRuby reference ;TI"Dcan be made persistent across processes by having each process ;TI"2register an object using the same dRuby name.;T:
@fileI"lib/drb/drb.rb;T:0@omit_headings_from_table_of_contents_below0o;;[;I"lib/drb/eq.rb;T;0o;;[;I"lib/drb/extserv.rb;T;0o;;[;I"lib/drb/extservm.rb;T;0o;;[;I"lib/drb/gw.rb;T;0o;;[;I"lib/drb/observer.rb;T;0o;;[;I"lib/drb/ssl.rb;T;0o;;[;I"lib/drb/timeridconv.rb;T;0o;;[;I"lib/drb/unix.rb;T;0;0;0[[
I"primary_server;TI"RW;T:publicTI"lib/drb/drb.rb;T[
@a
I"RW;T:privateF@c
[[[[I"
class;T[[;[[I"config;F@c
[I"current_server;F@c
[I"fetch_server;F@c
[I"
front;F@c
[I"
here?;F@c
[I"install_acl;F@c
[I"install_id_conv;F@c
[I"regist_server;F@c
[I"remove_server;F@c
[I"start_service;F@c
[I"stop_service;F@c
[I"thread;F@c
[I"
to_id;F@c
[I"to_obj;F@c
[I"uri;F@c
[:protected[[;[[I"
instance;T[[;[[;[[;[[@o
@c
[@q
@c
[@s
@c
[@u
@c
[@w
@c
[@y
@c
[@{
@c
[@}
@c
[@
@c
[@
@c
[@ƒ
@c
[@…
@c
[@‡
@c
[@‰
@c
[@‹
@c
[[U:RDoc::Context::Section[i0o;;[;0;0[@F
@I
@L
@O
@R
I"lib/drb/invokemethod.rb;T@U
@X
@[
@^
@^
cRDoc::TopLevel