New readmes

lib/a_star/README.docdown.md

@@ -0,0 +1,21 @@
+# `a_star` - [[ini-desc: a_star]]
+
+[[toc: a_star]]
+
+[[doc: a_star::a_star]]
+
+## Features
+
+[[uml: a_star | format: svg, mentities: a_star::Node;a_star::Link;a_star::Graph;a_star::AStarPath;a_star::PathContext;a_star::ConstantPathContext;a_star::WeightedPathContext;a_star::WeightedLink;a_star::TargetCondition]]
+
+[[features: a_star | mentities: a_star::Node;a_star::Link;a_star::Graph;a_star::AStarPath;a_star::PathContext;a_star::ConstantPathContext;a_star::WeightedPathContext;a_star::WeightedLink;a_star::TargetCondition;a_star::NamedNode;a_star::PositionedNamedNode;a_star::PositionedLink;a_star::PositionPathContext]]
+
+## Running the tests
+
+Run the nitunit automated tests with the following command:
+
+[[testing: a_star]]
+
+## Authors
+
+This project is maintained by [[ini-maintainer: a_star]].

lib/a_star/README.md

@@ -0,0 +1,73 @@
+# `a_star` - A* pathfinding in graphs
+
+* [Features](#Features)
+* [Running the tests](#Running-the-tests)
+* [Authors](#Authors)
+
+A single graph may have different properties according to the `PathContext` used
+
+Usage:
+
+~~~
+# Weighted graph (letters are nodes, digits are weights):
+#
+#     a -2- b
+#    /     /
+#   3     1
+#  /     /
+# c -3- d -8- e
+#
+var graph = new Graph[Node,WeightedLink]
+
+var na = new Node(graph)
+var nb = new Node(graph)
+var nc = new Node(graph)
+var nd = new Node(graph)
+var ne = new Node(graph)
+
+var lab = new WeightedLink(graph, na, nb, 2)
+var lac = new WeightedLink(graph, na, nc, 3)
+var lbd = new WeightedLink(graph, nb, nd, 1)
+var lcd = new WeightedLink(graph, nc, nd, 3)
+var lde = new WeightedLink(graph, nd, ne, 8)
+
+var context = new WeightedPathContext(graph)
+
+var path = na.path_to(ne, 100, context)
+assert path != null else print "No possible path"
+
+assert path.step == nb
+assert path.step == nd
+assert path.step == ne
+assert path.at_end_of_path
+~~~
+
+## Features
+
+![Diagram for `a_star`](uml-a_star.svg)
+
+* `AStarPath` - Result from path finding and a walkable path
+* `ConstantPathContext` - Simple context with constant cost on each links
+* `Graph` - General graph
+* `Link` - Link between two nodes and associated to a graph
+* `NamedNode` - Simple node with a name
+* `Node` - General graph node
+* `PathContext` - Context related to an evocation of pathfinding
+* `PositionPathContext` - Context for a graph with positions
+* `PositionedLink` - Link for nodes with a position
+* `PositionedNamedNode` - Node with a name and position
+* `TargetCondition` - Advanced path conditions with customizable accept states
+* `WeightedLink` - A `Link` with a `weight`
+* `WeightedPathContext` - A `PathContext` for graphs with `WeightedLink`
+
+## Running the tests
+
+Run the nitunit automated tests with the following command:
+
+~~~bash
+nitunit .
+~~~
+
+## Authors
+
+This project is maintained by **Alexis Laferrière <mailto:[email protected]>**.

lib/actors/README.docdown.md

@@ -0,0 +1,13 @@
+# `actors` - [[ini-desc: actors]]
+
+Example from `actors::agent_simulation`:
+
+[[code: actors::agent_simulation]]
+
+## Features
+
+[[features: actors | mentities: actors::Actor;actors::Mailbox;actors::Message;actors::Proxy;actors::ShutDownMessage;actors::Future;actors::SynchronizedCounter;actors::ActorClockAgent;actors::ActorAgent;actors::MessageClockAgent;actors::ClockAgentMessagenb_steps;actors::ClockAgentMessageagents;actors::ClockAgentMessagenb_finished;actors::ClockAgentMessagedo_step;actors::ClockAgentMessagefinished_step;actors::MessageAgent;actors::AgentMessagedo_step;actors::AgentMessageend_step;actors::AgentMessageothers;actors::AgentMessagecount;actors::AgentMessagegreet;actors::AgentMessagegreet_back;actors::ProxyClockAgent;actors::ProxyAgent;actors::ActorCreature;actors::MessageCreature;actors::CreatureMessageplace;actors::CreatureMessagecolor;actors::CreatureMessageid;actors::CreatureMessagecount;actors::CreatureMessagesamecount;actors::CreatureMessagerun;actors::CreatureMessageto_string;actors::ProxyCreature;actors::ActorFannkuchRedux;actors::MessageFannkuchRedux;actors::FannkuchReduxMessagep;actors::FannkuchReduxMessagepp;actors::FannkuchReduxMessagecount;actors::FannkuchReduxMessageprint_p;actors::FannkuchReduxMessagefirst_permutation;actors::FannkuchReduxMessagenext_permutation;actors::FannkuchReduxMessagecount_flips;actors::FannkuchReduxMessagerun_task;actors::FannkuchReduxMessagerun;actors::ProxyFannkuchRedux;actors::ActorWorker;actors::MessageWorker;actors::WorkerMessageget_byte;actors::WorkerMessageput_line;actors::WorkerMessagework;actors::ProxyWorker;actors::ActorA;actors::MessageA;actors::AMessagefoo;actors::AMessagebar;actors::ProxyA;actors::ActorThreadRing;actors::MessageThreadRing;actors::ThreadRingMessageid;actors::ThreadRingMessagenext;actors::ThreadRingMessagesend_token;actors::ProxyThreadRing]]
+
+## Authors
+
+This project is maintained by [[ini-maintainer: actors]].

lib/actors/README.md

@@ -1,72 +1,122 @@
-# Nit Actor Model
-
-This group introduces the `actors` module which contains the abstraction of a Nit Actor Model,
-based on Celluloid (https://github.com/celluloid/celluloid).
-
-## What is an actor ?
-
-An actor is an entity which receives messages and does some kind of computation based on it.
-An actor has a mailbox in which it receives its messages, and process them one at a time.
-
-
-## `actor` annotation
-
-The `actors` module introduces the annotation `actor` which is to be used on classes.
-This annotation transform a normal Nit class into an actor.
-
-In practice, it adds a new property `async` to the annotated class.
-When using `async` on your annotated class, this means that you want your calls to be asynchronous,
-executed by the actor.
-
-For instance, if you call `a.async.foo` and `foo` doesn't have a return value, it will send
-a message to the mailbox of the actor attached to `a` which will process it asynchronously.
-
-On the other hand, if you call `a.async.bar` and `bar` returns an`Int`, it will still send
-a message to the actor, but you'll get a `Future[Int]` to be able to retrieve the value.
-When using `join` on the future, the calling thread will wait until the value of the future is set.
-
-## Managing actors
-
-When you annotate a class with `actor` and create an instance of it with `new`, the actor is not
-automatically created (which means you can completely skip the use of the actors if you
-don't need them for a specific program).
-
-The `async` added property is actually created lazily when you use it.
-
-Actors are not automatically garbage collected, but you have solutions to terminate them
-if you need to. For this, you need to use the `async` property of your annotated class :
-
-* `async.terminate` sends a shutdown message to the actor telling him to stop, so he'll finish
-processing every other messages in his mailbox before terminating properly. Every other messages sent
-to this actor after he received the shutdown message won't be processed.
-* `async.terminate_now` sends a shutdown message too, but this time it places it first, so
-if the actor is processing one message now, the next one will be the shutdown message, discarding
-every messages in its mailbox.
-* `async.wait_termination` wait for the actor to terminate properly. This call is synchronous.
-* `async.kill`. If you really need this actor to stop, without any regards of what he was doing
-or in which state he'll leave the memory, you can with this call. it's synchronous but not really
-blocking, since it's direcly canceling the native pthread associated to the actor.
-
-For now, there isn't any mecanism to recreate and actor after it was terminated.
-Sending messages after terminating it results in unspecified behaviour.
-
-## Waiting for all actors to finish processing
-
-Let's imagine you create a whole bunch of actors and make them do things asynchronously from the main thread.
-You don't want your program to exit right after giving work to your actors.
-To prevent that, we added a mecanism that waits before all your actors finished all their messages
-before quitting.
-
-It's materialized by the `active_actors` property added to `Sys` which is a `ReverseBlockingQueue`.
-In short, the `is_empty` method on this list is blocking until the list is effectively empty.
-When every actors finished working, and we're sure they won't even send another message to another
-actor, `active_actors` is empty.
-
-You can use this property as a mean of synchronisation in some specific cases (for example if you're
-using actors for fork/join parallelism instead of concurrency).
-
-
-## Examples
-
-You can find example of differents small programs implemented with Nit actors in the `examples`
-directory. For a really simple example, you can check `examples/simple`.
+# `actors` - Nit Actor Model
+
+Example from `actors::agent_simulation`:
+
+~~~
+# a "Framework" to make Multi-Agent Simulations in Nit
+module agent_simulation is example, no_warning("missing-doc")
+
+import actors
+
+# Master of the simulation, it initiates the steps and waits for them to terminate
+class ClockAgent
+	actor
+
+	# Number of steps to do in the simulation
+	var nb_steps: Int
+
+	# List of Agents in the simulation
+	var agents: Array[Agent]
+
+	# Number of agents that finished their step
+	var nb_finished = 0
+
+	fun do_step do
+		for a in agents do a.async.do_step
+		nb_steps -= 1
+	end
+
+	fun finished_step do
+		nb_finished += 1
+		if nb_finished == agents.length then
+			nb_finished = 0
+			if nb_steps != 0 then async.do_step
+		end
+	end
+end
+
+class Agent
+	actor
+
+	# Doing a step in the simulation
+	fun do_step do
+	end
+
+	fun end_step do clock_agent.async.finished_step
+
+end
+
+redef class Sys
+	var clock_agent: ClockAgent is noautoinit,writable
+end
+~~~
+
+## Features
+
+* `AMessagebar`
+* `AMessagefoo`
+* `Actor` - Abstraction of an actor
+* `ActorA` - ###################### Actor classes #########################
+* `ActorAgent`
+* `ActorClockAgent` - ###################### Actor classes #########################
+* `ActorCreature` - ###################### Actor classes #########################
+* `ActorFannkuchRedux` - ###################### Actor classes #########################
+* `ActorThreadRing` - ###################### Actor classes #########################
+* `ActorWorker` - ###################### Actor classes #########################
+* `AgentMessagecount`
+* `AgentMessagedo_step`
+* `AgentMessageend_step`
+* `AgentMessagegreet`
+* `AgentMessagegreet_back`
+* `AgentMessageothers` - ###################### Redef classes #########################
+* `ClockAgentMessageagents`
+* `ClockAgentMessagedo_step`
+* `ClockAgentMessagefinished_step`
+* `ClockAgentMessagenb_finished`
+* `ClockAgentMessagenb_steps`
+* `CreatureMessagecolor`
+* `CreatureMessagecount`
+* `CreatureMessageid`
+* `CreatureMessageplace`
+* `CreatureMessagerun`
+* `CreatureMessagesamecount`
+* `CreatureMessageto_string`
+* `FannkuchReduxMessagecount`
+* `FannkuchReduxMessagecount_flips`
+* `FannkuchReduxMessagefirst_permutation`
+* `FannkuchReduxMessagenext_permutation`
+* `FannkuchReduxMessagep`
+* `FannkuchReduxMessagepp`
+* `FannkuchReduxMessageprint_p`
+* `FannkuchReduxMessagerun`
+* `FannkuchReduxMessagerun_task`
+* `Future` - The promise of a value which will be set asynchronously
+* `Mailbox` - A Blocking queue implemented from a `ConcurrentList`
+* `Message` - A Message received by a Mailbox
+* `MessageA` - ###################### Messages classes ######################
+* `MessageAgent`
+* `MessageClockAgent` - ###################### Messages classes ######################
+* `MessageCreature` - ###################### Messages classes ######################
+* `MessageFannkuchRedux` - ###################### Messages classes ######################
+* `MessageThreadRing` - ###################### Messages classes ######################
+* `MessageWorker` - ###################### Messages classes ######################
+* `Proxy` - Abstraction of proxies for threaded actors
+* `ProxyA`
+* `ProxyAgent`
+* `ProxyClockAgent`
+* `ProxyCreature`
+* `ProxyFannkuchRedux`
+* `ProxyThreadRing`
+* `ProxyWorker`
+* `ShutDownMessage` - A Message to Rule them all... properly shutdown an Actor
+* `SynchronizedCounter` - A counter on which threads can wait until its value is 0
+* `ThreadRingMessageid`
+* `ThreadRingMessagenext`
+* `ThreadRingMessagesend_token`
+* `WorkerMessageget_byte`
+* `WorkerMessageput_line`
+* `WorkerMessagework`
+
+## Authors
+
+This project is maintained by **Romain Chanoir <mailto:[email protected]>**.

lib/ai/README.docdown.md

@@ -0,0 +1,27 @@
+# `ai` - [[ini-desc: ai]]
+
+[[toc: ai]]
+
+## Features
+
+[[uml: ai | format: svg, mentities: ai::ai;ai::backtrack;ai::search]]
+
+### `backtrack` - Basic framework for active backtrack solver
+
+[[doc: ai::backtrack | no-synopsis]]
+
+Example from `ai::queens`:
+
+[[code: ai::queens]]
+
+### `search` - Basic framework for search problems and solver.
+
+[[doc: ai::search | no-synopsis]]
+
+Example from `ai::puzzle`:
+
+[[code: ai::puzzle]]
+
+## Authors
+
+This project is maintained by [[ini-maintainer: ai]].