From 7a64cdeb5588ab8e00d4fdb15bcd4b228e6c21c7 Mon Sep 17 00:00:00 2001
From: drbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>
Date: Sat, 23 Mar 2013 20:36:42 +0000
Subject: [PATCH] * lib/rinda/ring.rb: Added documentation for multicast
support.
* NEWS: Point to above documentation.
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@39897 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
---
ChangeLog | 6 ++++++
NEWS | 4 +++-
lib/rinda/ring.rb | 54 ++++++++++++++++++++++++++++++++++++++++++++---
3 files changed, 60 insertions(+), 4 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index fd2804bdae..1e83e70150 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+Sun Mar 24 05:36:29 2013 Eric Hodel <drbrain@segment7.net>
+
+ * lib/rinda/ring.rb: Added documentation for multicast support.
+
+ * NEWS: Point to above documentation.
+
Sun Mar 24 05:32:39 2013 Eric Hodel <drbrain@segment7.net>
* test/rinda/test_rinda.rb: Restore tests commented out while fixing
diff --git a/NEWS b/NEWS
index 818845711a..d8defce037 100644
--- a/NEWS
+++ b/NEWS
@@ -32,8 +32,10 @@ with all sufficient information, see the ChangeLog file.
* Net::SMTP
* Added Net::SMTP#rset to implement the RSET comamnd
+
* Rinda::RingServer, Rinda::RingFinger
- * Rinda now supports multicast sockets
+ * Rinda now supports multicast sockets. See Rinda::RingServer and
+ Rinda::RingFinger for details.
=== Stdlib compatibility issues (excluding feature bug fixes)
=== C API updates
diff --git a/lib/rinda/ring.rb b/lib/rinda/ring.rb
index fc85f44398..e9e92d2563 100644
--- a/lib/rinda/ring.rb
+++ b/lib/rinda/ring.rb
@@ -15,13 +15,25 @@ module Rinda
##
# A RingServer allows a Rinda::TupleSpace to be located via UDP broadcasts.
- # Service location uses the following steps:
+ # Default service location uses the following steps:
#
- # 1. A RingServer begins listening on the broadcast UDP address.
+ # 1. A RingServer begins listening on the network broadcast UDP address.
# 2. A RingFinger sends a UDP packet containing the DRb URI where it will
# listen for a reply.
# 3. The RingServer receives the UDP packet and connects back to the
# provided DRb URI with the DRb service.
+ #
+ # A RingServer requires a TupleSpace:
+ #
+ # ts = Rinda::TupleSpace.new
+ # rs = Rinda::RingServer.new
+ #
+ # RingServer can also listen on multicast addresses for announcements. This
+ # allows multiple RingServers to run on the same host. To use network
+ # broadcast and multicast:
+ #
+ # ts = Rinda::TupleSpace.new
+ # rs = Rinda::RingServer.new ts, %w[Socket::INADDR_ANY, 239.0.0.1 ff02::1]
class RingServer
@@ -48,7 +60,13 @@ module Rinda
end
##
- # Advertises +ts+ on the UDP broadcast address at +port+.
+ # Advertises +ts+ on the given +addresses+ at +port+.
+ #
+ # If +addresses+ is omitted only the UDP broadcast address is used.
+ #
+ # +addresses+ can contain multiple addresses. If a multicast address is
+ # given in +addresses+ then the RingServer will listen for multicast
+ # queries.
def initialize(ts, addresses=[Socket::INADDR_ANY], port=Ring_PORT)
@port = port
@@ -175,6 +193,33 @@ module Rinda
# TupleSpace. Typically, all a client needs to do is call
# RingFinger.primary to retrieve the remote TupleSpace, which it can then
# begin using.
+ #
+ # To find the first available remote TupleSpace:
+ #
+ # Rinda::RingFinger.primary
+ #
+ # To create a RingFinger that broadcasts to a custom list:
+ #
+ # rf = Rinda::RingFinger.new ['localhost', '192.0.2.1']
+ # rf.primary
+ #
+ # Rinda::RingFinger also understands multicast addresses and sets them up
+ # properly. This allows you to run multiple RingServers on the same host:
+ #
+ # rf = Rinda::RingFinger.new ['239.0.0.1']
+ # rf.primary
+ #
+ # You can set the hop count (or TTL) for multicast searches using
+ # #multicast_hops.
+ #
+ # If you use IPv6 multicast you may need to set both an address and the
+ # outbound interface index:
+ #
+ # rf = Rinda::RingFinger.new ['ff02::1']
+ # rf.multicast_interface = 1
+ # rf.primary
+ #
+ # At this time there is no easy way to get an interface index by name.
class RingFinger
@@ -238,6 +283,9 @@ module Rinda
##
# Creates a new RingFinger that will look for RingServers at +port+ on
# the addresses in +broadcast_list+.
+ #
+ # If +broadcast_list+ contains a multicast address then multicast queries
+ # will be made using the given multicast_hops and multicast_interface.
def initialize(broadcast_list=@@broadcast_list, port=Ring_PORT)
@broadcast_list = broadcast_list || ['localhost']