File	Date	Author	Commit
ext_include	2013-06-30	Keith Godfrey	[378fc9] preparing initial SF git repo
ext_src	2013-06-30	Keith Godfrey	[378fc9] preparing initial SF git repo
include	2013-06-30	Keith Godfrey	[378fc9] preparing initial SF git repo
src	2013-06-30	Keith Godfrey	[378fc9] preparing initial SF git repo
testing	2013-06-30	Keith Godfrey	[378fc9] preparing initial SF git repo
Makefile	2013-06-30	Keith Godfrey	[378fc9] preparing initial SF git repo
Makefile.inc	2013-06-30	Keith Godfrey	[378fc9] preparing initial SF git repo
README	2013-06-30	Keith Godfrey	[378fc9] preparing initial SF git repo
Release-notes	2013-06-30	Keith Godfrey	[52ccf7] minor updates to release notes
UsingMPI	2013-06-30	Keith Godfrey	[378fc9] preparing initial SF git repo
gpl.txt	2013-06-30	Keith Godfrey	[378fc9] preparing initial SF git repo

Read Me

ABOUT

SpikeOS is a combination between a programming framework and a 
distributed operating system. It manages the execution and 
communication between large numbers of 'microthreads'. A 
microthread here is defined as a semi-autonomous process that
performs a specific task, but a task that is far too trivial 
to dedicate an operating system thread to run. While a normal
operating system may operate on hundreds or perhaps thousands
of independent threads, SpikeOS was meant to manage the 
execution of potentially millions of microthreads. Microthreads 
communicate via a message passing interface and synchronization
between them is handled by SpikeOS. SpikeOS manages the
details of parallel programming so the developer is free to
not worry about these.

SpikeOS was originally designed to facilitate implementation
of large scale neural networks, with each microthread representing
a simulated spiking neuron, hence the name. It is also amenable
to being used for simulating or representing independent but
interacting elements, possibly even game characters in a simulated world.
For a spiking neural model, SpikeOS should be able to simulate
up to 10K simple neurons per CPU core in real time, based on 1ms update
cycles. The exact number of course depending on the complexity of 
the neurons, the speed of the CPU, and the amount of communication 
occuring between neurons (e.g., the average number of spikes per
second and the amount of bi-directional communication). For 
other uses that have less frequent update cycles, the complexity
of each task can be increased while still being able to run
similarly large numbers of tasks in real time. 

Microthreads operate through co-operative multitasking and are 
distributed among CPU cores, with one operating system thread 
managing a pool of microthreads on each CPU core. A group of cores
on a single machine (ie, one address space) is termed a 'colony'.
Each colony can have multiple 'cores', with each core mapping to
an individual pthread. 

Microthread run on a single time on each simulation cycle. Messages 
between microthreads are cached during each cycle and delivered to
the recipient on the subsequent cycle. The design was intended to 
minimize internal use of synchronization calls (e.g., mutex) and
to allow microthreads to be distributed across a network, such 
as in a cluster. NOTE: there is a two cycle communication latency 
if jobs are not in the same address space - i.e., are on different
machines, or in SpikeOS parlance, are parts of different colonies.
A group of one or more cores in the same address space is a colony.

Because of synchronization issues, messaging in SpikeOS is relatively
expensive, and so SpikeOS is most useful for applications where
communication between microthreads is infrequent. There are reduced-
overhead ways to communicate through broadcast mechanisms and 'static'
jobs (ie, jobs that are cloned and exist on each core)

The default behavior is now to save the state on termination,
so each simulation can be resumed at a future date. The runtime
is specified on the command line.


USING SPIKE-OS

To develop an application under SpikeOS, the programming goal must 
be able to be broken down into individual jobs (i.e., microthreads). 
Each job is implemented as a subclass of MicroThread, and submitted
to the SpikeOS kernel. When all jobs are submitted and SpikeOS 
started, SpikeOS will call the run() routine for each job once per 
simulation cycle.

When all jobs have gone to sleep, and there is no further 
communication activity, SpikeOS transitions to a shutdown state.
Individual jobs can communicate with external entities to achieve
the desired programming goal, or, in the case of a simulation
environment, information from sleeping jobs can be queried in
the shutdown state and the results of the simulation computed
and stored. 

It should be noted that when programming under SpikeOS, it is
useful to have a different programming perspective, seeing things
from the perspective of individual microthreads and how they 
send and receive messages from each other. 

Further documentation may be forthcoming. For now, the best way 
to see how SpikeOS works is to examine the 'testing' directory to
see how testing/debugging applications are structured. By examining
the code, it will become apparent that there are several microthread 
super-classes and that the description provided here is very limited.
The source code itself has limited documentation.

As SpikeOS is in active development as of Dec 2011. Any feedback on 
problems encountered will be very valuable for improving quality 
and functionality.

Best of luck,
Keith
aquilonis@earthlink.net