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"