needlethreads

by @dr-Jonas-Birch

Don't use threads. Use needles.

Needlethreads is a light-weight thread implementation, written from scratch in C. It is very easy to use, highly optimized and it does not in any way use Posix Threads. It is based on a combination of an internal heap allocated with mmap(2) plus Inter Process Communication (IPC) between forks.

Features

• Local variables
• Global variables, shared by the threads (the "needles") with automatic mutex protection
• Multi-CPU core support (by default spawn_multiple() creates as many needles as you have CPU cores)
• You may also use spawn_single() to use as many needles as you'd like. Remember to call awaitneedles() when you're done so you don't create zombie processes. This is done automatically when using spawn_multiple()

Installation

make
sudo make install

If it succeeds to compile, but fails to install. Make sure that the Makefile contains the right library directory.

API

ninit(int32 size)

Initializes the library and allocates the shared heap. Size is in bytes but you can give kb(20) as an argument to allocate 20 KB. You may also use mb() to the same extent, but for megabytes.

let(variablename)

Declares a variable which is shared between forks. All variables are 64 bit in size (plus 8 additional bits for the mutex locks). You may use all alpha-numeric characters as well as the prime symbol '

You define your variables using let() in the main program before you allocate the needles. Then you use get() and put() (see below) in the needles' program code.

spawn_single(int16 _nid, int16 core, cb callback)

• NID is a Needle ID which must be unique and non zero.
• Core is what CPU core to bind the needle to. If you have four cores, this value should be 0, 1, 2 or 3.
• The callback is the needle's main() function. The signature is void _callback(int16 _nid)
• ALWAYS call awaitneedles() without arguments when you are done spawning the needles using this single-function.

spawn_multiple(cb callback)

This function spawns four needles if you have four CPU cores. It handles the awaiting automatically.

get(variablename)

Returns the value of the shared variable as an unsigned long integer. If two needles try to access the same variable at the same time the mutex lock kicks in automatically and the second process waits for the first. This works the same for reads and writes.

put(variablename, value)

Changes the value of the shared variable to a value of the form unsigned long integer. The mutex lock applies (see get() above).

nuninit()

Un-initializes the library. Make sure that all needles are dead before you issue this function call.

Example program

#include <needle.h>

extern Memspace Heap;
extern int16 nid;
extern int16 numneedles;

void _callback(int16 _nid) {
    unsigned long int n;

    n = (unsigned long int)get(myvar);
    n++;
    put(myvar, n);

    printf("[%d] Thread end\n", (unsigned int)nid);
    fflush(stdout);

    return;
}

int main(int argc, char *argv[]) {
    int16 i;

    ninit(kb(20));
    let(myvar);

    printf("Spawning needlethreads...\n");
    fflush(stdout);

    for (i=1; i<11; i++)
        spawn_single(i, (i % 4), &_callback);
    awaitneedles();

    printf("\nAll threads terminated. Value of myvar is:\n");
    printf("%d\n", (unsigned int)((unsigned long int)get(myvar)));
    fflush(stdout);

    nuninit();

    return 0;
}

Example program compilation

gcc example.c -o example -lneedle

or:

make example

Contact

Do you have questions or do you wish to maintain this library? Contact me at [email protected]. Please do also check out my popular coding Youtube channel, @dr-Jonas-Birch