# module DRb::DRbProtocol

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.

### Public Class Methods

add_protocol(prot) click to toggle source

Add a new protocol to the DRbProtocol module.

    # File lib/drb/drb.rb, line 723
    def add_protocol(prot)
      @protocol.push(prot)
    end

open(uri, config, first=true) click to toggle source

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.

    # File lib/drb/drb.rb, line 735
    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) click to toggle source

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.

    # File lib/drb/drb.rb, line 763
    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) click to toggle source

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.

    # File lib/drb/drb.rb, line 784
    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

### Private Instance Methods

add_protocol(prot) click to toggle source

Add a new protocol to the DRbProtocol module.

    # File lib/drb/drb.rb, line 723
    def add_protocol(prot)
      @protocol.push(prot)
    end

open(uri, config, first=true) click to toggle source

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.

    # File lib/drb/drb.rb, line 735
    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) click to toggle source

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.

    # File lib/drb/drb.rb, line 763
    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) click to toggle source

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.

    # File lib/drb/drb.rb, line 784
    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