←  APIs and Utilities

ComputerCraft | Programmable Computers for Minecraft

»

Swarm API

Yevano's Photo Yevano 30 May 2013

Hello everybody. I'm fairly new to the community, so this is the first API I've made public. I've created an API for networking turtles together for doing parallel tasks such as building, item gathering, etc. This API is in beta, so it does not currently aim to keep compatibility with older versions of the API. http://pastebin.com/gzEYHUWr


Documentation

Red:something that will be fixed/changed in later updates.
Strike-through: API usage which is deprecated.

shared/Swarm

This table holds all of the main functions you will need to use to get your swarm up and running.

shared/Swarm.run()

The main swarm thread. This should be run inside of a ThreadPool so that this function does not block code. This thread handles networking messages.

master/Swarm

Master-specific swarm functions.

master/Swarm.init(channel, modemSide)

channel:number the channel to open the network on
modemSide:string the side of the computer to look for the modem peripheral

Initializes the Swarm network. The channel used must be the same used in the turtles that wish to join the swarm.

master/Swarm.allocTurtles(amount)

amount:number the amount of turtles to allocate
Attempts to allocate amount turtles. Returns nil if not enough turtles are available, or a table of Turtle objects, otherwise.

master/Swarm.submitTask(task, turtles)

task:function(workerID) the function to be run by the turtles
turtles:table[Turtle] a table containing all of the turtles which will run the task

Submits a task to all the turtles in the table turtles.

slave/Swarm

Slave-specific swarm functions.

slave/Swarm.init(id, channel, modemSide)

id:number the id of the swarm master
channel:number the channel to open the network on
modemSide:string the side of the computer to look for the modem peripheral

Initializes the Swarm network. The channel used must be the same used in the turtles that wish to join the swarm.

slave/Swarm.join()

Sends a JOIN packet to the swarm master. This function does not error if the master does not receive the packet, or some other internal error occurs on the other end.

slave/Swarm.leave()

Sends a LEAVE packet to the swarm master. This function does not error if the master does not receive the packet, or some other internal error occurs on the other end.

master/Hook

Functions for hooking to events generated by the swarm.

master/Hook.add(event, listener)

event:string the event to hook onto
listener:function(event, id:number) the function to run when the event is fired

Adds a hook.

master/Hook.remove(event, id)

event:string the event to remove the hook from
id:number the id of the hook to remove

Removes a hook.

master/Hook.call(event, obj)

event:string the event to fire
obj:any the event data to pass (preferably, but not necessarily, a table)

Calls a hook.

shared/ThreadPool

An object used to manage multiple threads in a more convenient way than the parallel API.

shared/ThreadPool.new()

Creates a new ThreadPool.

shared/ThreadPool:add(func)

func:function() the function used to create a new thread

Add a new thread to this ThreadPool. This can be done before or after the ThreadPool has begun executing threads.

shared/ThreadPool:waitForAll()

Waits for all threads to finish executing. This can safely be run inside another ThreadPool if need be.

slave/Navigation

Turtle functions for convenient navigation.

slave/Navigation.detourFunctions()

Detours the native turtle API functions to allow for movement tracking. This function must be called for the Navigation functions to work correctly.

slave/Navigation.restoreFunctions()

Restores the native turtle API to its original state. This function should be called when the Navigation functions are no longer needed.

slave/Navigation.setOrientation(dir, pos)

dir:number the initial direction of the turtle. Use Direction.NORTH|SOUTH|EAST|WEST.
pos:Vector the initial position of the turtle.

slave/Navigation.goTo(pos)

pos:Vector the position to go to

Attempts to navigate the turtle to the given position. This function does not provide error handling in the event of failure.

slave/Navigation.turnTo(dir)

dir:number the direction to turn to. Use Direction.NORTH|SOUTH|EAST|WEST.

Turns to the given direction. This function always makes either two right turns, one right turn, one left turn, or zero turns.

slave/Navigation.dir()

Returns the stored direction.

slave/Navigation.pos()

Returns the stored position.

shared/NetManager

Functions for sending and receiving messages in the swarm.

shared/NetManager.open(channel, modemSide)

channel:number the channel that messages should be sent on
modemSide:string the side to look for the modem peripheral

This function is used by Swarm.init to open up network communications. This shouldn't be called by user code.

shared/NetManager.send(id, message)

id:number the ID of the remote computer to send a message to
message:table the message table to send. Reserved table entries are __SENDER, __SENDER_TYPE, and __RECIPIENT.

Sends a message to the remote computer with the given id.

shared/NetManager.receive(id, message)

Blocks until a message intended for the local computer has been received. This does not need to be called by user code. Instead, hook the NetMessage event.


Usage Tutorial

The API is not difficult to use, but the setup may at first be confusing. Follow these steps and you should have no problems.

Physical Setup

For this tutorial, we will just place a master computer next to a turtle which will be our worker. Do this in a clear area so that you have plenty of room for testing.

Install

Type these commands into console of the master to get the installer and run it:

pastebin get gzEYHUWr installer
installer master


Type these commands into the console of the turtle to get the installer and run it:

pastebin get gzEYHUWr installer
installer slave


Testing

In the master computer, download the master test file from pastebin id T8PXQUhB.
In the turtle, download the slave test file from pastebin id RHzEW536.

Now you can do some testing! Make sure you run the master program first, and then run the turtle program with the id of the master computer as an argument. When you run the turtle test program, the turtle should move up and then back down. Make sure it has fuel, or the movement functions will fail.

Now that you know the swarm works, mess around with the test code and see if you can make something interesting. Try changing the argument to Swarm.allocTurtle on line 21 of the master program to something higher. You will have to run the slave program on more turtles if you give it a higher value. You could also try changing the task code that gets sent to the turtles on line 9 of the master program.


Download

For now, I am distributing the download as an archive file. If anyone has a problem with this, I might put all the files up on pastebin, but please realize that this is a hassle on my part because of how many files I would have to maintain.

Download Link


Update[5/31]: Use the GitHub repo instead: Yevano/swarm-api


Notes

You may use and distribute this code as much as you like. Credit to me is appreciated, but there's nothing stopping you from claiming it as your own. Suggestions and comments are appreciated.
Quote

H4X0RZ's Photo H4X0RZ 30 May 2013

Sounds interesting :D

OFFTOPIC:
250th post. Lame -_-
Quote

bjornir90's Photo bjornir90 31 May 2013

Looks really cool ! I tried to do something like this but I failed .... Good luck with this :)
Quote

Yevano's Photo Yevano 31 May 2013

I have created a GitHub repo for the API. OP has also been updated with documentation for NetManager functions.
Quote

Yevano's Photo Yevano 01 Jun 2013

Updated OP with a brief usage tutorial to make the setup process less confusing. Thanks to Mast3rPlan for making the installer <3.
Quote

Xakorik's Photo Xakorik 19 Jun 2013

The master version of the test script isn't working for me:

string:7: attempt to index ? (a nil value)
Quote