# 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