Module: DRb::DRbProtocol

Defined in:
lib/drb/drb.rb,
lib/drb/drb.rb

Overview

Module managing the underlying network protocol(s) used by drb.

By default, drb uses the DRbTCPSocket protocol. Other protocols can be defined. A protocol must define the following class methods:

[open(uri, config)] Open a client connection to the server at +uri+,
                    using configuration +config+.  Return a protocol
                    instance for this connection.
[open_server(uri, config)] Open a server listening at +uri+,
                           using configuration +config+.  Return a
                           protocol instance for this listener.
[uri_option(uri, config)] Take a URI, possibly containing an option
                          component (e.g. a trailing '?param=val'),
                          and return a [uri, option] tuple.

All of these methods should raise a DRbBadScheme error if the URI does not identify the protocol they support (e.g. “druby:” for the standard Ruby protocol). This is how the DRbProtocol module, given a URI, determines which protocol implementation serves that protocol.

The protocol instance returned by #open_server must have the following methods:

accept

Accept a new connection to the server. Returns a protocol instance capable of communicating with the client.

close

Close the server connection.

uri

Get the URI for this server.

The protocol instance returned by #open must have the following methods:

send_request (ref, msg_id, arg, b)

Send a request to ref with the given message id and arguments. This is most easily implemented by calling DRbMessage.send_request, providing a stream that sits on top of the current protocol.

recv_reply

Receive a reply from the server and return it as a [success-boolean, reply-value] pair. This is most easily implemented by calling DRb.recv_reply, providing a stream that sits on top of the current protocol.

alive?

Is this connection still alive?

close

Close this connection.

The protocol instance returned by #open_server().accept() must have the following methods:

recv_request

Receive a request from the client and return a [object, message, args, block] tuple. This is most easily implemented by calling DRbMessage.recv_request, providing a stream that sits on top of the current protocol.

send_reply(succ, result)

Send a reply to the client. This is most easily implemented by calling DRbMessage.send_reply, providing a stream that sits on top of the current protocol.

close

Close this connection.

A new protocol is registered with the DRbProtocol module using the add_protocol method.

For examples of other protocols, see DRbUNIXSocket in drb/unix.rb, and HTTP0 in sample/http0.rb and sample/http0serv.rb in the full drb distribution.

Class Method Summary collapse

Class Method Details

.add_protocol(prot) ⇒ Object

Add a new protocol to the DRbProtocol module.



724
725
726
 
# File 'lib/drb/drb.rb', line 724

def add_protocol(prot)
  @protocol.push(prot)
end

.auto_load(uri) ⇒ Object

:nodoc:



802
803
804
805
806
 
# File 'lib/drb/drb.rb', line 802

def auto_load(uri)  # :nodoc:
  if /\Adrb([a-z0-9]+):/ =~ uri
    require("drb/#{$1}") rescue nil
  end
end

.open(uri, config, first = true) ⇒ Object

Open a client connection to uri with the configuration config.

The DRbProtocol module asks each registered protocol in turn to try to open the URI. Each protocol signals that it does not handle that URI by raising a DRbBadScheme error. If no protocol recognises the URI, then a DRbBadURI error is raised. If a protocol accepts the URI, but an error occurs in opening it, a DRbConnError is raised.

Raises:



736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
 
# File 'lib/drb/drb.rb', line 736

def open(uri, config, first=true)
  @protocol.each do |prot|
    begin
      return prot.open(uri, config)
    rescue DRbBadScheme
    rescue DRbConnError
      raise($!)
    rescue
      raise(DRbConnError, "#{uri} - #{$!.inspect}")
    end
  end
  if first && (config[:auto_load] != false)
    auto_load(uri)
    return open(uri, config, false)
  end
  raise DRbBadURI, 'can\'t parse uri:' + uri
end

.open_server(uri, config, first = true) ⇒ Object

Open a server listening for connections at uri with configuration config.

The DRbProtocol module asks each registered protocol in turn to try to open a server at the URI. Each protocol signals that it does not handle that URI by raising a DRbBadScheme error. If no protocol recognises the URI, then a DRbBadURI error is raised. If a protocol accepts the URI, but an error occurs in opening it, the underlying error is passed on to the caller.

Raises:



764
765
766
767
768
769
770
771
772
773
774
775
776
 
# File 'lib/drb/drb.rb', line 764

def open_server(uri, config, first=true)
  @protocol.each do |prot|
    begin
      return prot.open_server(uri, config)
    rescue DRbBadScheme
    end
  end
  if first && (config[:auto_load] != false)
    auto_load(uri)
    return open_server(uri, config, false)
  end
  raise DRbBadURI, 'can\'t parse uri:' + uri
end

.uri_option(uri, config, first = true) ⇒ Object

Parse uri into a [uri, option] pair.

The DRbProtocol module asks each registered protocol in turn to try to parse the URI. Each protocol signals that it does not handle that URI by raising a DRbBadScheme error. If no protocol recognises the URI, then a DRbBadURI error is raised.

Raises:



785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
 
# File 'lib/drb/drb.rb', line 785

def uri_option(uri, config, first=true)
  @protocol.each do |prot|
    begin
      uri, opt = prot.uri_option(uri, config)
      # opt = nil if opt == ''
      return uri, opt
    rescue DRbBadScheme
    end
  end
  if first && (config[:auto_load] != false)
    auto_load(uri)
    return uri_option(uri, config, false)
  end
  raise DRbBadURI, 'can\'t parse uri:' + uri
end