Welcome to Raisin

NOTE: This documentation was written with the expectation that you're familiar with the Minecraft mod ComputerCraft. If you are, give yourself a pat on the back, if not, don't worry. As long as you understand Lua things should make sense.

Welcome to Raisin! Just a note before we dive into this, I understand that coroutines are not considered the easiest thing in the world, and if you're one of those people that just don't understand them don't worry, we all were there too at one point or another. If I have done my job right, I think that this API should be straightforward and easy to understand without having the foggiest idea of what coroutines are. As a matter of fact this may be able to aid in your bridging the gap from being a "parallel scrub" to a "coroutine supreme". As such, the documentation will be designed with this in mind.

Raisin is an easy to use coroutine manager built for use in general purpose Lua. Let's start by explaining what's so magical about Raisin.

The largest part of Raisin's design is its threads. Threads are functions that are provided to Raisin with the intent to be run in parallel with one or more other functions. With Raisin we can do a couple of things to these threads. We can pause or resume them, and shuffle the priority in which they execute. If you're at all familiar with CC's Parallel API, you know that functions are run in the order that you put them into the function:

parallel.waitForAll(a, b, c, d)

When this is executed, function a, then b, then c, and lastly d will be called in a loop until one dies. If c dies for example, then the execution loop would be a, b, d. c simply gets taken out of the loop.

With Raisin that capability is dynamic, and can be tweaked whenever you so choose. Additionally, you know that depending on which function you call, waitForAny, or waitForAll determines when execution of the coroutines gets terminated, and until then you really don't have much control. With Raisin you do have this ability, by either toggling the state of the threads (they can either be enabled or disabled), you can determine when you want a thread to be paused or resumed, or by means of the onDeath function, leading to some pretty powerful functionality.

The second part of Raisin's design is the power of groups. Groups can simply be considered containers for threads that have additional input on when that thread gets resumed in the loop. Groups allow for control over large amounts of threads. Say you have a hundred or so threads and you want to be able to control them with the call of a function. Groups allow for just that, without them, you would have to hang onto a table of threads and iteratively call them and that just gets ugly. I did it for you, you're welcome. <3