Module multi

The module is responsible for handling multiple robots and providing interprocess communication.

Authors: Sten Gruener.

Description

The module is responsible for handling multiple robots and providing interprocess communication. Includes useful features like broadcast and group voting. It was one of design goals to achieve independence of other modules: multi does not require thu usage of any low- or high-level modules at all, this decision is completely up to the user.

Working philosophy.

Before working with multi it is important to understand some basic working principles. The process which is responsible for handling robots is a so called dispatcher, this process is the main part of the module. Once started, the dispatcher will maintain a list of robots who are under his 'control'. All robots inside of this group are reached e.g. by a broadcast. It is rational to keep the dispatcher's PID inside of each robot belonging to the group, which will allow it to call functions provided by the multi module.

Note that a new dispatcher can be spawned by a robot who is already a member of some group allowing to create hierarchical groups structure quickly.

Data Types

addtype()

addtype() = pid() | [pid()]

Function Index

add/2Adds the pid or list of pids into the Dispatchers list.
barrier/1Allows time-synchronization, unblocks at the same time in every thread.
broadcast/2Broadcasts the message to the group except the sender.
create_robot/4Spawns a robot-thread and adds the PID to the list including robot into the group.
get_list/1Returns the list of the PID of robots in the group.
start/0Starts the dispatcher.
vote/2Gives a functionality of a acknowledged-selecting one robot.

Function Details

add/2

add(Dispatcherid::pid(), T::addtype()) -> ok | {error, atom()}

Adds the pid or list of pids into the Dispatchers list. In contrast to add_robot the process has to be already spawned by the user.

barrier/1

barrier(Dispatcherid::pid()) -> ok | {error, atom()}

Allows time-synchronization, unblocks at the same time in every thread. Useful for creating syncpoints e.g. when all robots need to start at the same time. Please note that 100% sync is not possible, there will always be some slight time-variation during unlock.

Note: barrier needs to be called on every robot in the group, it will unblock only after every robot has called it.

broadcast/2

broadcast(Dispatcherid::Pid, Message::any()) -> ok | {error, atom()}

Broadcasts the message to the group except the sender.

Note: the message {test} from PID X will be broadcasted as {X, {test}}.

create_robot/4

create_robot(Dispatcherid::pid(), Module::atom(), Function::atom(), Args::[any()]) -> pid() | {error, atom()}

Spawns a robot-thread and adds the PID to the list including robot into the group.
A good design-philosophy would be to pass the Dispatcherid as the first argument.
A typical call initializing 2 robots could be:

Driver = ps:start(),
Dispatcherid = multi:start(),
multi:createRobot(Dispatcherpid, multibouncer, thread, [Dispatcherid, Driver, 0]),
multi:createRobot(Dispatcherpid, multibouncer, thread, [Dispatcherid, Driver, 1]).

with:

thread(Dispatcherid, Driverid, Playerid) ->
ps:init(Driverid, Playerid).

get_list/1

get_list(Dispatcherid::pid()) -> [pid()] | {error, atom()}

Returns the list of the PID of robots in the group.

start/0

start() -> pid() | {error, atom()}

Starts the dispatcher

vote/2

vote(Dispatcherid::pid(), Participate::binary()) -> pid()

Gives a functionality of a acknowledged-selecting one robot. Useful for sharing resources or distributing roles. Participate can be true or false indicating robots will to be elected. The winner is selected between participating robots with uniform probability in order to ensure fair chances of being elected. Note: if no process sets Participate=true dispatchers pid will be returned

Note: like barrier needs to be called on every robot in the group, it will unblock only after every robot has called it.


Generated by EDoc, Aug 13 2009, 23:20:23.