roby 0.7

data/doc/tutorials/06-Overview.rdoc

@@ -0,0 +1,40 @@
+{Previous tutorial}[link:files/doc/tutorials/05-ErrorHandling_rdoc.html]
+= Overview of other Roby features
+
+=== Transactions
+
+Transactions are a central tool for plan modification in Roby. They are a
+representation of a plan _modification_, i.e. of the changes that are necessary
+to bring the plan which is being executed in a new, desired state. It is
+therefore a safe tool for asynchronous plan modification and execution:
+
+* the decision tools can build a new plan without taking into account the
+  changes brought by execution
+* the plan execution can safely assess if the new plans are still compatible
+  with the built transactions, and refuse applying a transaction if it is not
+  safe.
+
+Ideally, a cooperation protocol should be implemented to properly handle
+conflicting situations (where the transaction cannot be applied). For now, only
+very crude means are used. This is one of the future evolutions of Roby.
+
+Please refer to my PhD thesis for a more extensive presentation of this feature.
+
+=== Multi-robot execution
+
+All models presented here are valid in multi-robot systems. In particular, the
+transactions tool allow to build cooperatively a new plan (something which may
+take time) and apply the plan when a common ground has been found by all the
+present systems.
+
+The communication layer, as it is implemented for now, is only valid for
+bi-robot systems. One of its most interesting features is that it does not take
+the presence of a communication link for granted. It is possible for the two
+robots to execute the parts of the plan that do not need communication, and to
+diagnose the loss of communication (for instance, deciding that the joint plan
+is not valid anymore after a given timeout). 
+
+The communication layer extension to a true multi-robot setup is also for a
+future evolution of Roby. It can be easily be done to a certain extent.
+Reaching a full multi-robot plan execution would take more time.
+

data/doc/videos.rdoc

@@ -0,0 +1,69 @@
+= Videos
+
+== Normal operations
+
+Those videos don't show what Roby itself does, only results showing
+robots (real and in simulation) acting as they are controlled by a
+Roby application.
+
+=== Single robot navigation
+
+http://roby.rubyforge.org/videos/perception_loops.avi
+
+What we see in this video is the perception loop (whose visible part is the DEM
+building) being handled by Roby. The perception updates are triggered by Roby
+on the basis of state events: they are triggered by the translation of the
+robot and the change of heading, to reduce the number of times it is actually done.
+
+=== Bi-robot navigation
+
+http://roby.rubyforge.org/videos/birobot.avi
+
+What we see in this video is the cooperation between a rover and an UAV for a
+navigation task. Both robots, as well as the common part of their joint plan is
+written in and managed by Roby.  Including part of the data transfer process.
+This bi-robot setup has also successfully been tested on real robots, with an
+iRobot ATRV and a Yamaha RMAX helicopter.
+
+In this video, the rover plans its path (the line on the ground) in a
+traversability map (red/green map: red is non-traversable, green is
+traversable). It also generates a set of regions of interest for him. Those
+regions are then considered by the UAV which decides how it will schedule its
+own perception. When the UAV does have perceived a zone, it informs the rover
+and sends it the relevant data. The rover can then update its own map.
+
+== Error handling
+=== Rflex repaired
+
+http://roby.rubyforge.org/videos/rflex_repaired.avi
+
+This is a simple example of asynchronous repairs.  In this video, the
+microcontroller which drives the robot's motors can give us spurious
+<tt>BRAKES_ON</tt> messages. Our problem is that the Roby controller must
+determine if the message is spurious, or if brakes are actually set by the means
+of an emergency switch for instance. To do that, an error handling is set up,
+which wait for a few seconds and tests the <tt>BRAKES_ON</tt> state of the
+robot. If the brakes are reported as off, then the robot can start moving again.
+Otherwise, the error was a rightful one and should be handled by other means.
+
+=== P3d repaired
+
+http://roby.rubyforge.org/videos/p3d_repaired.avi.
+
+In this video, the system handles a problem with DEM generation ("DEM" means
+"Digital Elevation Map". It is a representation of the terrain the robot is on).
+Due to localization issues, it is possible to have a very bad DEM in which the
+robot cannot move. If that happens, the locomotion activity (P3d::Track) emits
+the +blocked+ event. Our way to handle it in three steps:
+1. a new DEM perception is done. As the robot is not moving, it should give a
+   better result. This is called the "Stage 1 handler" in the video.
+2. if the robot is still blocked, the "Stage 2 handler" completely reinitializes
+   the DEM and do a local update.
+3. if the fault remains, the problem does not lie in the DEM perception process,
+   but in the fact that the robot is actually blocked. The error must therefore be
+   handled by other means.
+
+At all times, if the robot moves more than a given threshold, the problem was
+actually the DEM perception process and the error handler is reset at the first
+stage for following operations.
+

data/ext/droby/dump.cc

@@ -0,0 +1,175 @@
+#include <ruby.h>
+#include <intern.h>
+#include <st.h>
+#include <set>
+
+static VALUE mRoby;
+static VALUE mRobyDistributed;
+static VALUE cDRbObject;
+static VALUE cSet;
+static VALUE cValueSet;
+static ID id_droby_dump;
+static ID id_remote_id;
+static ID id_append;
+
+/* 
+ * Document-class: Roby::Distributed
+ */
+
+/* call-seq:
+ *   format(object, peer) => formatted_object
+ *
+ * Formats +object+ so that it is ready to be dumped by Marshal.dump for
+ * sending to +peer+. This means that if the object has a droby_dump method, it
+ * is called to get a marshallable object which represents +object+. Moreover,
+ * if +peer+ responds to #incremental_dump?(object), this is called to
+ * determine wether a full dump is required or if sending a
+ * Roby::Distributed::RemoteID for remote reference is enough.
+ *
+ * If the object is not a DRbObject and does not define a #droby_dump method,
+ * it is proxied through a DRbObject if it present in
+ * Distributed.allow_remote_access. Otherwise, we will try to dump it as-is.
+ */
+static VALUE droby_format(int argc, VALUE* argv, VALUE self)
+{
+    VALUE object, destination;
+    rb_scan_args(argc, argv, "11", &object, &destination);
+
+    if (RTEST(rb_obj_is_kind_of(object, cDRbObject)))
+	return object;
+
+    if (RTEST(rb_respond_to(object, id_droby_dump)))
+    {
+	if (!NIL_P(destination) && RTEST(rb_funcall(destination, rb_intern("incremental_dump?"), 1, object)))
+	    return rb_funcall(object, id_remote_id, 0);
+	return rb_funcall(object, id_droby_dump, 1, destination);
+    }
+
+    VALUE remote_access = rb_iv_get(self, "@allowed_remote_access");
+    int i;
+    for (i = 0; i < RARRAY(remote_access)->len; ++i)
+    {
+	if (rb_obj_is_kind_of(object, RARRAY(remote_access)->ptr[i]))
+	    return rb_class_new_instance(1, &object, cDRbObject);
+    }
+
+    return object;
+}
+
+typedef struct DROBY_DUMP_ITERATION_ARG
+{
+    VALUE result;
+    VALUE dest;
+} DROBY_DUMP_ITERATION_ARG;
+
+static VALUE array_dump_element(VALUE element, DROBY_DUMP_ITERATION_ARG* arg)
+{   
+    VALUE args[2] = { element, arg->dest };
+    rb_ary_push(arg->result, droby_format(2, args, mRobyDistributed));
+    return Qnil; 
+}
+
+// call-seq:
+//   droby_dump(dest) => dumped_array
+// 
+// Creates a copy of this Array with all its values formatted for marshalling
+// using Distributed.format.
+static VALUE array_droby_dump(VALUE self, VALUE dest)
+{
+    VALUE result = rb_ary_new();
+    struct RArray* array = RARRAY(self);
+    int i;
+
+    VALUE el[2] = { Qnil, dest };
+    for (i = 0; i < array->len; ++i)
+    {
+	el[0] = array->ptr[i];
+	rb_ary_push(result, droby_format(2, el, mRobyDistributed));
+    }
+
+    return result;
+}
+
+static int hash_dump_element(VALUE key, VALUE value, DROBY_DUMP_ITERATION_ARG* arg)
+{
+    VALUE args_key[2] = { key, arg->dest };
+    key = droby_format(2, args_key, mRobyDistributed);
+    VALUE args_value[2] = { value, arg->dest };
+    value = droby_format(2, args_value, mRobyDistributed);
+    rb_hash_aset(arg->result, key, value);
+    return ST_CONTINUE;
+}
+
+// call-seq:
+//   droby_dump => dumped_hash
+// 
+// Creates a copy of this Hash with all its values formatted for marshalling
+// using Distributed.format. The keys are not modified.
+static VALUE hash_droby_dump(VALUE self, VALUE dest)
+{
+    DROBY_DUMP_ITERATION_ARG arg = { rb_hash_new(), dest };
+    rb_hash_foreach(self, (int(*)(ANYARGS)) hash_dump_element, (VALUE)&arg);
+    return arg.result;
+}
+
+static VALUE appendable_dump_element(VALUE value, DROBY_DUMP_ITERATION_ARG* arg)
+{
+    VALUE args[2] = { value, arg->dest };
+    rb_funcall(arg->result, id_append, 1, droby_format(2, args, mRobyDistributed));
+    return Qnil;
+}
+
+// Creates a copy of this Set with all its values formatted for marshalling
+// using Distributed.format
+static VALUE set_droby_dump(VALUE self, VALUE dest)
+{
+    DROBY_DUMP_ITERATION_ARG arg = { rb_class_new_instance(0, 0, cSet), dest };
+    rb_iterate(rb_each, self, RUBY_METHOD_FUNC(appendable_dump_element), (VALUE)&arg);
+    return arg.result;
+}
+
+// Creates a copy of this ValueSet with all its values formatted for
+// marshalling using Distributed.format
+static VALUE value_set_droby_dump(VALUE self, VALUE dest)
+{
+    VALUE result = rb_class_new_instance(0, 0, cValueSet);
+    std::set<VALUE>* result_set;
+    Data_Get_Struct(result, std::set<VALUE>, result_set);
+
+    std::set<VALUE> const * source_set;
+    Data_Get_Struct(self, std::set<VALUE>, source_set);
+
+    VALUE el[2] = { Qnil, dest };
+    for (std::set<VALUE>::const_iterator it = source_set->begin(); it != source_set->end(); ++it)
+    {
+	el[0] = *it;
+	result_set->insert(droby_format(2, el, mRobyDistributed));
+    }
+
+    return result;
+}
+
+extern "C" void Init_roby_marshalling()
+{
+    id_droby_dump = rb_intern("droby_dump");
+    id_remote_id = rb_intern("remote_id");
+    id_append = rb_intern("<<");
+    
+    cDRbObject = rb_const_get(rb_cObject, rb_intern("DRbObject"));
+    cValueSet  = rb_const_get(rb_cObject, rb_intern("ValueSet"));
+    cSet       = rb_const_get(rb_cObject, rb_intern("Set"));
+
+    /* */
+    mRoby            = rb_define_module("Roby");
+    /* */
+    mRobyDistributed = rb_define_module_under(mRoby, "Distributed");
+
+    rb_define_method(rb_cArray , "droby_dump" , RUBY_METHOD_FUNC(array_droby_dump)     , 1);
+    rb_define_method(rb_cHash  , "droby_dump" , RUBY_METHOD_FUNC(hash_droby_dump)      , 1);
+    rb_define_method(cSet      , "droby_dump" , RUBY_METHOD_FUNC(set_droby_dump)       , 1);
+    rb_define_method(cValueSet , "droby_dump" , RUBY_METHOD_FUNC(value_set_droby_dump) , 1);
+
+    rb_define_singleton_method(mRobyDistributed, "format", RUBY_METHOD_FUNC(droby_format), -1);
+
+}
+

data/ext/droby/extconf.rb

@@ -0,0 +1,3 @@
+require 'mkmf'
+create_makefile("roby_marshalling")
+

data/ext/graph/algorithm.cc

@@ -0,0 +1,746 @@
+#include "graph.hh"
+#include <boost/graph/depth_first_search.hpp>
+#include <boost/graph/breadth_first_search.hpp>
+#include <boost/iterator/transform_iterator.hpp>
+#include <boost/iterator/filter_iterator.hpp>
+#include <boost/graph/connected_components.hpp>
+#include <boost/graph/topological_sort.hpp>
+#include <boost/bind.hpp>
+#include <boost/graph/reverse_graph.hpp>
+#include "undirected_graph.hh"
+#include "undirected_dfs.hh"
+#include <queue>
+#include <functional>
+
+typedef RubyGraph::vertex_iterator	vertex_iterator;
+typedef RubyGraph::vertex_descriptor	vertex_descriptor;
+typedef RubyGraph::edge_iterator	edge_iterator;
+typedef RubyGraph::edge_descriptor	edge_descriptor;
+
+static VALUE graph_view_of(VALUE self)
+{ return rb_iv_get(self, "@__bgl_real_graph__"); }
+
+using namespace boost;
+using namespace std;
+
+static ID id_new;
+static VALUE utilrbValueSet;
+
+template<typename T>
+struct Queue : std::queue<T>
+{
+    T& top() { return this->front(); }
+    T const& top() const { return this->front(); }
+};
+
+namespace details {
+    // Reverse graphs do not have an adjacency_iterator
+    template<typename Graph>
+    struct vertex_range< boost::reverse_graph<Graph, Graph&>, false>
+    {
+	typedef typename Graph::adjacency_iterator iterator;
+	typedef std::pair<iterator, iterator> range;
+
+	static range get(RubyGraph::vertex_descriptor v, 
+		boost::reverse_graph<Graph, Graph&> const& graph) 
+	{ return adjacent_vertices(v, graph.m_g); }
+    };
+
+    template<typename Graph>
+    struct vertex_range< boost::reverse_graph<Graph, Graph const&>, false>
+    {
+	typedef typename Graph::adjacency_iterator iterator;
+	typedef std::pair<iterator, iterator> range;
+
+	static range get(RubyGraph::vertex_descriptor v, 
+		boost::reverse_graph<Graph, Graph const&> const& graph) 
+	{ return adjacent_vertices(v, graph.m_g); }
+    };
+}
+
+/* If +key+ is found in +assoc+, returns its value. Otherwise, initializes 
+ * +key+ to +default_value+ in +assoc+ and returns it
+ */
+template<typename Key, typename Value>
+Value& get(map<Key, Value>& assoc, Key const& key, Value const& default_value)
+{
+    typename map<Key, Value>::iterator it = assoc.find(key);
+    if (it != assoc.end())
+	return it->second;
+
+    tie(it, tuples::ignore) = assoc.insert( make_pair(key, default_value) );
+    return it->second;
+}
+
+/* If +key+ is found in +assoc+, returns its value. Otherwise, returns +default_value+
+ */
+template<typename Key, typename Value>
+Value const& get(map<Key, Value> const& assoc, Key const& key, Value const& default_value)
+{
+    typename map<Key, Value>::const_iterator it = assoc.find(key);
+    if (it != assoc.end())
+	return it->second;
+
+    return default_value;
+}
+
+/* ColorMap is a map with default value */
+class ColorMap : private map<vertex_descriptor, default_color_type>
+{
+    template<typename Key, typename Value>
+    friend Value& get(map<Key, Value>&, Key const&, Value const&);
+
+    default_color_type const default_value;
+
+    typedef map<vertex_descriptor, default_color_type> Super;
+
+public:
+
+    typedef Super::key_type	key_type;
+    typedef Super::value_type	value_type;
+
+    Super::clear;
+
+    ColorMap()
+	: default_value(color_traits<default_color_type>::white()) {}
+
+    default_color_type& operator[](vertex_descriptor key)
+    { 
+	default_color_type& c = get(*this, key, default_value); 
+	return c;
+    }
+
+};
+
+typedef list<vertex_descriptor> vertex_list;
+
+struct vertex_recorder : public default_dfs_visitor
+{
+public:
+    set<VALUE>&  component;
+    vertex_recorder( set<VALUE>& component )
+	: component(component) { }
+
+    template<typename G>
+    void discover_vertex(vertex_descriptor u, G const& g)
+    { component.insert(g[u]); }
+};
+
+
+static std::set<VALUE>& rb_to_set(VALUE object)
+{
+    if (!RTEST(rb_obj_is_kind_of(object, utilrbValueSet)))
+	rb_raise(rb_eArgError, "expected a ValueSet");
+
+    std::set<VALUE>* result_set;
+    Data_Get_Struct(object, set<VALUE>, result_set);
+    return *result_set;
+}
+
+/** Converts a std::set<VALUE> into a ValueSet object 
+ * After this method, +source+ is empty */
+static VALUE set_to_rb(set<VALUE>& source)
+{
+    VALUE result = rb_funcall(utilrbValueSet, id_new, 0);
+    set<VALUE>* result_set;
+    Data_Get_Struct(result, set<VALUE>, result_set);
+
+    result_set->swap(source);
+    return result;
+}
+
+typedef std::set<VALUE> ValueSet;
+/* Adds in +result+ all components generated by the items in [it, end). We 
+ * assume that there is no component which includes more than one item in
+ * [it, end) */
+template<typename Graph, typename Iterator>
+static void graph_components_i(std::list<ValueSet>& result, Graph const& g, Iterator it, Iterator end, bool include_singletons)
+{
+    ColorMap   colors;
+
+    result.push_front(ValueSet());
+    for (; it != end; ++it)
+    {
+	if (0 == *it) // elements not in +g+  are handled by graph_result_root_descriptor
+	    continue;
+	if (colors[*it] != color_traits<default_color_type>::white())
+	    continue;
+
+	ValueSet& component(*result.begin());
+	depth_first_visit(g, *it, vertex_recorder(component), make_assoc_property_map(colors));
+	if (component.size() > 1 || include_singletons)
+	    result.push_front(ValueSet());
+	else
+	    component.clear();
+    }
+    result.pop_front();
+}
+
+/** If +v+ is found in +g+, returns the corresponding vertex_descriptor. Otherwise,
+ * add a singleton component to +result+ and return NULL.
+ */
+static vertex_descriptor graph_components_root_descriptor(std::list<ValueSet>& result, VALUE v, VALUE g, bool include_singletons)
+{
+    vertex_descriptor d;
+    bool exists;
+    tie(d, exists) = rb_to_vertex(v, g);
+    if (! exists)
+    {
+	if (include_singletons)
+	{
+	    ValueSet component;
+	    component.insert(v);
+	    result.push_back(component);
+	}
+	return NULL;
+    }
+    return d;
+}
+template<typename Graph>
+static VALUE graph_do_generated_subgraphs(int argc, VALUE* argv, Graph const& g, VALUE self)
+{
+    VALUE roots = Qnil, include_singletons;
+    if (rb_scan_args(argc, argv, "11", &roots, &include_singletons) == 1)
+	include_singletons = Qtrue;
+
+    bool with_singletons = RTEST(include_singletons) ? true : false;
+    std::list<ValueSet> result;
+    if (NIL_P(roots))
+    {
+	RubyGraph::vertex_iterator it, end;
+	tie(it, end) = vertices(g);
+	// call graph_components_i with all root vertices
+	// in +graph+
+	graph_components_i(result, g, 
+		make_filter_iterator(
+		    bind(
+			vertex_has_adjacent_i<Graph, false>, 
+			_1, ref(g)
+		    ), it, end
+		),
+		make_filter_iterator(
+		    bind(
+			vertex_has_adjacent_i<Graph, false>, 
+			_1, ref(g)
+		    ), end, end
+		), with_singletons
+	    );
+    }
+    else
+    {
+	std::set<VALUE>& root_set = rb_to_set(roots);
+	std::set<VALUE>::const_iterator 
+	    begin = root_set.begin(),
+	    end   = root_set.end();
+
+	// call graph_components_i with all vertices given in as argument
+	graph_components_i(result, g, 
+		make_transform_iterator(begin, 
+		    bind(graph_components_root_descriptor, ref(result), _1, self, with_singletons)
+		),
+		make_transform_iterator(end,
+		    bind(graph_components_root_descriptor, ref(result), _1, self, with_singletons)
+		), with_singletons);
+    }
+
+    // Now convert the result into a Ruby array
+    VALUE rb_result = rb_ary_new();
+    for (std::list<ValueSet>::iterator it = result.begin(); it != result.end(); ++it)
+	rb_ary_push(rb_result, set_to_rb(*it));
+    return rb_result;
+}
+/*
+ * call-seq:
+ *   graph.components(seeds = nil, include_singletons = true)	=> components
+ *
+ * Returns an array of vertex sets. Each set is a connected component of
+ * +graph+. If a list of vertices +seeds+ is provided, returns only the
+ * components the vertices are part of. The graph is treated as if it were not
+ * directed.
+ *
+ * If +include_singletons+ is false and +seeds+ is non-nil, then +components+
+ * will not include the singleton components { v } where v is in +seeds+
+ */
+static VALUE graph_components(int argc, VALUE* argv, VALUE self)
+{ 
+    VALUE seeds, include_singletons;
+    rb_scan_args(argc, argv, "02", &seeds, &include_singletons);
+    if (argc == 1)
+	include_singletons = Qtrue;
+
+    // Compute the connected components
+    RubyGraph const& g = graph_wrapped(self);
+
+    typedef std::map<vertex_descriptor, int> ComponentMap;
+    ComponentMap component_map;
+    ColorMap	 color_map;
+    int count = connected_components(utilmm::make_undirected_graph(g),
+	    make_assoc_property_map(component_map), 
+	    boost::color_map( make_assoc_property_map(color_map) ));
+
+    VALUE ret = rb_ary_new2(count);
+    std::vector<bool>  enabled_components;
+    std::vector<VALUE> components(count);
+    if (0 == argc) 
+	enabled_components.resize(count, true);
+    else
+    {
+	enabled_components.resize(count, false);
+	std::set<VALUE>& seed_set = rb_to_set(seeds);
+	for (std::set<VALUE>::const_iterator it = seed_set.begin(); it != seed_set.end(); ++it)
+	{
+	    VALUE rb_vertex = *it;
+
+	    vertex_descriptor v; bool in_graph;
+	    tie(v, in_graph) = rb_to_vertex(rb_vertex, self);
+	    if (in_graph)
+	    {
+		int v_c = component_map[v];
+		enabled_components[v_c] = true;
+	    }
+	    else if (RTEST(include_singletons))
+		rb_ary_push(ret, rb_ary_new3(1, rb_vertex));
+	}
+    }
+
+    // Add empty array for all enabled components
+    for (int i = 0; i < count; ++i)
+    {
+	if (! enabled_components[i]) continue;
+	VALUE ary = components[i] = rb_ary_new();
+	rb_ary_store(ret, i, ary);
+    }
+
+    // Add the vertices to their corresponding Ruby component
+    for (ComponentMap::const_iterator it = component_map.begin(); it != component_map.end(); ++it)
+    {
+	int c = it->second;
+	if (! enabled_components[c])
+	    continue;
+
+	rb_ary_push(components[c], g[it->first]);
+    }
+
+    if (argc > 0 && !RTEST(include_singletons))
+    {
+	// Remove the remaining singletons
+	for (int i = 0; i < count; ++i)
+	{
+	    if (! enabled_components[i])
+		continue;
+	    if (RARRAY(components[i])->len == 1)
+		rb_ary_store(ret, i, Qnil);
+	}
+    }
+
+    // Remove all unused component slots (disabled components)
+    rb_funcall(ret, rb_intern("compact!"), 0);
+    return ret;
+}
+
+/*
+ * call-seq:
+ *   undirected_graph.components(seeds = nil, include_singletons = true) => components
+ *
+ * Returns an array of vertex sets. Each set is a connected component of +graph+. If
+ * a list of vertices is provided, returns only the components the vertices are part of.
+ * The graph is treated as if it were not directed. It is equivalent to graph.components.
+ */
+static
+VALUE graph_undirected_components(int argc, VALUE* argv, VALUE self)
+{ return graph_components(argc, argv, graph_view_of(self)); }
+
+/* call-seq:
+ *   graph.generated_subgraph([v1, v2, ...][, include_singletons])		   => components
+ *
+ * Returns an array of vertex sets. Each set is the component that can be
+ * reached from one of the given seed. If no initial vertex is given, the graph
+ * roots are taken.
+ */
+static VALUE graph_generated_subgraphs(int argc, VALUE* argv, VALUE self)
+{ return graph_do_generated_subgraphs(argc, argv, graph_wrapped(self), self); }
+
+/* call-seq:
+ *   graph.generated_subgraph([v1, v2, ...])		   => components
+ *
+ * Like Graph#generated_subgraph, but on the reverse graph of +graph+ (where edges has
+ * been swapped)
+ */
+static VALUE graph_reverse_generated_subgraphs(int argc, VALUE* argv, VALUE self)
+{ 
+    VALUE real_graph = rb_iv_get(self, "@__bgl_real_graph__");
+    return graph_do_generated_subgraphs(argc, argv, make_reverse_graph(graph_wrapped(real_graph)), real_graph); 
+}
+
+static const int VISIT_TREE_EDGES = 1;
+static const int VISIT_BACK_EDGES = 2;
+static const int VISIT_FORWARD_OR_CROSS_EDGES = 4;
+static const int VISIT_NON_TREE_EDGES = 6;
+static const int VISIT_ALL_EDGES = 7;
+
+struct ruby_dfs_visitor : public default_dfs_visitor
+{
+
+    int m_mode;
+    ruby_dfs_visitor(int mode)
+	: m_mode(mode) { } 
+
+    template<typename E, typename G>
+    void tree_edge(E e, G const& graph)
+    { yield_edge(e, graph, VISIT_TREE_EDGES); }
+    template<typename E, typename G>
+    void back_edge(E e, G const& graph)
+    { yield_edge(e, graph, VISIT_BACK_EDGES); }
+    template<typename E, typename G>
+    void forward_or_cross_edge(E e, G const& graph)
+    { yield_edge(e, graph, VISIT_FORWARD_OR_CROSS_EDGES); }
+
+    template<typename E, typename G>
+    void yield_edge(E e, G const& graph, int what)
+    {
+	if (!(what & m_mode))
+	    return;
+
+	VALUE rb_source = graph[source(e, graph)];
+	VALUE rb_target = graph[target(e, graph)];
+	VALUE info = graph[e].info;
+	rb_yield_values(4, rb_source, rb_target, info, INT2FIX(what));
+    }
+};
+
+template<typename G>
+static bool search_terminator(vertex_descriptor u, G const& g)
+{ 
+    VALUE thread = rb_thread_current();
+    bool result = RTEST(rb_thread_local_aref(thread, rb_intern("@prune")));
+    if (result)
+	rb_thread_local_aset(thread, rb_intern("@prune"), Qfalse);
+    return result;
+}
+
+/* call-seq:
+ *  graph.prune
+ *
+ * In #each_dfs, call this method to stop developing the current branch
+ */
+static VALUE graph_prune(VALUE self)
+{
+    VALUE thread = rb_thread_current();
+    rb_thread_local_aset(thread, rb_intern("@prune"), Qtrue);
+    return Qtrue;
+}
+
+template<typename Graph>
+static VALUE graph_each_dfs(VALUE self, Graph const& graph, VALUE root, VALUE mode)
+{
+    rb_thread_local_aset(rb_thread_current(), rb_intern("@prune"), Qfalse);
+
+    vertex_descriptor v; bool exists;
+    tie(v, exists) = rb_to_vertex(root, self);
+    if (! exists)
+	return self;
+
+    map<vertex_descriptor, default_color_type> colors;
+    depth_first_visit(graph, v, ruby_dfs_visitor(FIX2INT(mode)), 
+	    make_assoc_property_map(colors), &search_terminator<Graph>);
+    return self;
+}
+
+/* call-seq:
+ *  graph.each_dfs(root, mode) { |source, dest, info, kind| ... }
+ *
+ * Enumerates edges of the graph following a depth-first search order.
+ * +mode+ is a filter on the kind of edge which shall be enumerated (TREE,
+ * FORWARD_OR_CROSS, BACK and ALL) and +root+ is the source of the search
+ */
+static VALUE graph_direct_each_dfs(VALUE self, VALUE root, VALUE mode)
+{
+    RubyGraph& graph = graph_wrapped(self);
+    return graph_each_dfs(self, graph, root, mode);
+}
+
+/* call-seq:
+ *  graph.each_dfs(root, mode) { |source, dest, info, kind| ... }
+ *
+ * Enumerates edges of the graph following a depth-first search order.
+ * +mode+ is a filter on the kind of edge which shall be enumerated (TREE,
+ * NON_TREE and ALL) and +root+ is the source of the search
+ */
+static VALUE graph_reverse_each_dfs(VALUE self, VALUE root, VALUE mode)
+{
+    VALUE real_graph = graph_view_of(self);
+    RubyGraph& graph = graph_wrapped(real_graph);
+    return graph_each_dfs(real_graph, make_reverse_graph(graph), root, mode);
+}
+
+/* call-seq:
+ *  graph.each_dfs(root, mode) { |source, dest, info, kind| ... }
+ *
+ * Enumerates edges of the graph following a depth-first search order.
+ * +mode+ is a filter on the kind of edge which shall be enumerated (TREE,
+ * FORWARD_OR_CROSS, BACK and ALL) and +root+ is the source of the search
+ */
+static VALUE graph_undirected_each_dfs(VALUE self, VALUE root, VALUE mode)
+{
+    VALUE real_graph = graph_view_of(self);
+    RubyGraph& graph = graph_wrapped(real_graph);
+    typedef utilmm::undirected_graph<RubyGraph> Undirected;
+    Undirected undirected(graph);
+
+    vertex_descriptor v; bool exists;
+    tie(v, exists) = rb_to_vertex(root, real_graph);
+    if (! exists)
+	return self;
+
+    ColorMap colors;
+    edge_iterator ei, ei_end;
+    for(tie(ei, ei_end) = edges(graph); ei != ei_end; ++ei)
+	graph[*ei].color = boost::white_color;
+
+    rb_thread_local_aset(rb_thread_current(), rb_intern("@prune"), Qfalse);
+    utilmm::undirected_depth_first_visit(undirected, v, ruby_dfs_visitor(FIX2INT(mode)),
+	    make_assoc_property_map(colors), 
+	    utilmm::make_undirected_edge_map(get(&EdgeProperty::color, graph)), 
+	    &search_terminator<Undirected>);
+    return self;
+}
+
+struct ruby_reachable_visitor : default_dfs_visitor
+{
+    bool& m_found;
+    vertex_descriptor m_target;
+
+    ruby_reachable_visitor(bool& found, vertex_descriptor target)
+	: m_found(found), m_target(target) { m_found = false; }
+
+    template<typename E, typename G>
+    void tree_edge(E e, G const& graph)
+    { 
+	if (m_target == target(e, graph))
+	    m_found = true;
+    }
+};
+
+struct ruby_reachable_terminator
+{ 
+    bool const& found;
+    ruby_reachable_terminator(bool const& found)
+	: found(found) { }
+
+    template<typename G>
+    bool operator()(vertex_descriptor u, G const& g) const { return found; }
+};
+
+/* call-seq:
+ *  graph.reachable?(v1, v2)
+ *
+ * Returns true if v2 can be reached from v1
+ */
+VALUE graph_reachable_p(VALUE self, VALUE source, VALUE target)
+{
+    RubyGraph& graph = graph_wrapped(self);
+    vertex_descriptor s, t; bool exists;
+    tie(s, exists) = rb_to_vertex(source, self);
+    if (! exists)
+	return Qfalse;
+    tie(t, exists) = rb_to_vertex(target, self);
+    if (! exists)
+	return Qfalse;
+
+    map<vertex_descriptor, default_color_type> colors;
+    bool found;
+    depth_first_visit(graph, s, ruby_reachable_visitor(found, t), 
+	    make_assoc_property_map(colors), ruby_reachable_terminator(found));
+
+    return found;
+}
+
+
+struct ruby_bfs_visitor : public default_bfs_visitor
+{
+    int m_mode;
+    ruby_bfs_visitor(int mode)
+	: m_mode(mode) { } 
+
+    template<typename E, typename G>
+    void tree_edge(E e, G const& graph)
+    { yield_edge(e, graph, VISIT_TREE_EDGES); }
+    template<typename E, typename G>
+    void non_tree_edge(E e, G const& graph)
+    { yield_edge(e, graph, VISIT_NON_TREE_EDGES); }
+    template<typename E, typename G>
+    void yield_edge(E e, G const& graph, int what)
+    {
+	if (!(what & m_mode))
+	    return;
+
+	VALUE source_vertex = graph[source(e, graph)];
+	VALUE target_vertex = graph[target(e, graph)];
+	VALUE info = graph[e].info;
+	rb_yield_values(4, source_vertex, target_vertex, info, INT2FIX(what));
+    }
+};
+
+template<typename Graph>
+static VALUE graph_each_bfs(VALUE self, Graph const& graph, VALUE root, VALUE mode)
+{
+    int intmode = FIX2INT(mode);
+    if ((intmode & VISIT_NON_TREE_EDGES) && ((intmode & VISIT_NON_TREE_EDGES) != VISIT_NON_TREE_EDGES))
+	rb_raise(rb_eArgError, "cannot use FORWARD_OR_CROSS and BACK");
+
+    vertex_descriptor v; bool exists;
+    tie(v, exists) = rb_to_vertex(root, self);
+    if (! exists)
+	return self;
+
+    rb_thread_local_aset(rb_thread_current(), rb_intern("@prune"), Qfalse);
+    map<vertex_descriptor, default_color_type> colors;
+    Queue<vertex_descriptor> queue;
+    breadth_first_search(graph, v, queue, ruby_bfs_visitor(intmode), 
+	    make_assoc_property_map(colors));
+    return self;
+}
+
+/* call-seq:
+ *  graph.each_bfs(root, mode) { |source, dest, info, kind| ... }
+ *
+ * Enumerates edges of the graph following a breadth-first search order.
+ * +mode+ is a filter on the kind of edge which shall be enumerated (TREE,
+ * NON_TREE and ALL) and +root+ is the source of the search
+ */
+static VALUE graph_direct_each_bfs(VALUE self, VALUE root, VALUE mode)
+{
+    RubyGraph& graph = graph_wrapped(self);
+    return graph_each_bfs(self, graph, root, mode);
+}
+
+/* call-seq:
+ *  graph.each_bfs(root, mode) { |source, dest, info, kind| ... }
+ *
+ * Enumerates edges of the graph following a breadth-first search order.
+ * +mode+ is a filter on the kind of edge which shall be enumerated (TREE,
+ * NON_TREE and ALL) and +root+ is the source of the search
+ */
+static VALUE graph_reverse_each_bfs(VALUE self, VALUE root, VALUE mode)
+{
+    VALUE real_graph = graph_view_of(self);
+    RubyGraph& graph = graph_wrapped(real_graph);
+    return graph_each_bfs(real_graph, make_reverse_graph(graph), root, mode);
+}
+
+/* call-seq:
+ *  graph.each_bfs(root, mode) { |source, dest, info, kind| ... }
+ *
+ * Enumerates edges of the graph following a breadth-first search order.
+ * +mode+ is a filter on the kind of edge which shall be enumerated (TREE,
+ * NON_TREE and ALL) and +root+ is the source of the search
+ */
+static VALUE graph_undirected_each_bfs(VALUE self, VALUE root, VALUE mode)
+{
+    VALUE real_graph = graph_view_of(self);
+    RubyGraph& graph = graph_wrapped(real_graph);
+    return graph_each_bfs(real_graph, utilmm::make_undirected_graph(graph), root, mode);
+}
+
+/* call-seq:
+ *  graph.topological_sort => array
+ *
+ * Returns a topological sorting of this graph
+ */
+static VALUE graph_topological_sort(int argc, VALUE* argv, VALUE self)
+{
+    VALUE rb_result;
+    rb_scan_args(argc, argv, "01", &rb_result);
+    if (NIL_P(rb_result))
+	rb_result = rb_ary_new();
+    else
+	rb_ary_clear(rb_result);
+
+    RubyGraph& graph = graph_wrapped(self);
+    typedef std::vector<RubyGraph::vertex_descriptor> Result;
+    Result result;
+
+    map<vertex_descriptor, default_color_type> colors;
+    try
+    {
+	topological_sort(graph, std::back_inserter(result), 
+		boost::color_map(make_assoc_property_map(colors)));
+
+	for (int i = result.size() - 1; i >= 0; --i)
+	    rb_ary_push(rb_result, graph[result[i]]);
+	return rb_result;
+    }
+    catch(boost::not_a_dag) {}
+    rb_raise(rb_eArgError, "the graph is not a DAG");
+}
+
+/**********************************************************************
+ *  Extension initialization
+ */
+
+/*
+ * Document-class: BGL
+ *
+ * The BGL module defines a Graph class and a Vertex module. The Graph class can
+ * be used to manipulate graphs where vertices are referenced by a graph descriptor
+ * (Graph#add_edge, Graph#add_vertex, ...). However, the preferred way to us BGL is
+ * to mix Vertex in the vertex objects and use the associated methods:
+ * 
+ *   class MyNode
+ *     include BGL::Graph
+ *   end
+ *   graph = Graph.new
+ *   v1, v2 = MyNode.new, MyNode.new
+ *   graph.link(v1, v2, [])
+ *   ...
+ *   v1.each_child_object { ... }
+ */
+
+/*
+ * Document-class: BGL::Graph
+ *
+ * A directed graph between Ruby objects. See BGL documentation.
+ */
+
+/*
+ * Document-class: BGL::Vertex
+ *
+ * A module to be mixed in objects used as vertices in Graph. It
+ * allows to use the same object in more than one graph.
+ */
+
+void Init_graph_algorithms()
+{
+    id_new = rb_intern("new");
+
+    bglModule = rb_define_module("BGL");
+    bglGraph  = rb_define_class_under(bglModule, "Graph", rb_cObject);
+    rb_define_const(bglGraph , "TREE"             , INT2FIX(VISIT_TREE_EDGES));
+    rb_define_const(bglGraph , "FORWARD_OR_CROSS" , INT2FIX(VISIT_FORWARD_OR_CROSS_EDGES));
+    rb_define_const(bglGraph , "BACK"             , INT2FIX(VISIT_BACK_EDGES));
+    rb_define_const(bglGraph , "NON_TREE"         , INT2FIX(VISIT_NON_TREE_EDGES));
+    rb_define_const(bglGraph , "ALL"              , INT2FIX(VISIT_ALL_EDGES));
+
+    rb_define_method(bglGraph, "components",   RUBY_METHOD_FUNC(graph_components), -1);
+    rb_define_method(bglGraph, "generated_subgraphs",   RUBY_METHOD_FUNC(graph_generated_subgraphs), -1);
+    rb_define_method(bglGraph, "each_dfs",	RUBY_METHOD_FUNC(graph_direct_each_dfs), 2);
+    rb_define_method(bglGraph, "each_bfs",	RUBY_METHOD_FUNC(graph_direct_each_bfs), 2);
+    rb_define_method(bglGraph, "reachable?", RUBY_METHOD_FUNC(graph_reachable_p), 2);
+    rb_define_method(bglGraph, "prune",		RUBY_METHOD_FUNC(graph_prune), 0);
+    rb_define_method(bglGraph, "topological_sort",		RUBY_METHOD_FUNC(graph_topological_sort), -1);
+
+    bglReverseGraph = rb_define_class_under(bglGraph, "Reverse", rb_cObject);
+    rb_define_method(bglReverseGraph, "generated_subgraphs",RUBY_METHOD_FUNC(graph_reverse_generated_subgraphs), -1);
+    rb_define_method(bglReverseGraph, "each_dfs",   RUBY_METHOD_FUNC(graph_reverse_each_dfs), 2);
+    rb_define_method(bglReverseGraph, "each_bfs",   RUBY_METHOD_FUNC(graph_reverse_each_bfs), 2);
+    rb_define_method(bglReverseGraph, "prune",	    RUBY_METHOD_FUNC(graph_prune), 0);
+
+    bglUndirectedGraph = rb_define_class_under(bglGraph, "Undirected", rb_cObject);
+    rb_define_method(bglUndirectedGraph, "generated_subgraphs",  RUBY_METHOD_FUNC(graph_undirected_components), -1);
+    rb_define_method(bglUndirectedGraph, "each_dfs",	RUBY_METHOD_FUNC(graph_undirected_each_dfs), 2);
+    rb_define_method(bglUndirectedGraph, "each_bfs",	RUBY_METHOD_FUNC(graph_undirected_each_bfs), 2);
+    rb_define_method(bglUndirectedGraph, "prune",	RUBY_METHOD_FUNC(graph_prune), 0);
+
+    utilrbValueSet = rb_define_class("ValueSet", rb_cObject);
+}
+