375 posts
USA
Posted 30 May 2013 - 08:30 PM
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
[anchor='Documentation']
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.
[anchor='UsageTutorial']
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.
[anchor='Download']
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
[anchor='Notes']
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.
[anchor='Documentation']
Documentation
Red:something that will be fixed/changed in later updates.
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.
[anchor='UsageTutorial']
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.
[anchor='Download']
Download
Download Link
Update[5/31]: Use the GitHub repo instead: Yevano/swarm-api
[anchor='Notes']
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.
