Arachne  0.1
Classes | Functions | Variables
Arachne Public API


struct  Arachne::ThreadId
class  Arachne::SpinLock
class  Arachne::ConditionVariable


void Arachne::init (int *argcp, const char **argv)
void Arachne::shutDown ()
void Arachne::waitForTermination ()
void Arachne::yield ()
void Arachne::sleep (uint64_t ns)
void Arachne::block ()
void Arachne::signal (ThreadId id)
void Arachne::join (ThreadId id)
ThreadId Arachne::getThreadId ()
void Arachne::setErrorStream (FILE *stream)
void Arachne::testInit ()
void Arachne::testDestroy ()
template<typename _Callable , typename... _Args>
ThreadId Arachne::createThread (_Callable &&__f, _Args &&...__args)


const Arachne::ThreadId Arachne::NullThread

Detailed Description

Most of the functions in this API, with the exception of Arachne::init(), Arachne::shutDown(), Arachne::waitForTermination(), and Arachne::createThread(), should only be called from within Arachne threads.

In order to allow unit tests in non-Arachne threads to run, Arachne::testInit() should be called once before all unit tests run, and Arachne::testDestroy() should be called once after all unit tests finish.

Function Documentation

void Arachne::block ( )

Block the current thread until another thread invokes join() with the current thread's ThreadId.

template<typename _Callable , typename... _Args>
ThreadId Arachne::createThread ( _Callable &&  __f,
_Args &&...  __args 

Spawn a new thread with a function and arguments.

__fThe main function for the new thread.
__argsThe arguments for __f. The total size of the arguments cannot exceed 48 bytes, and arguments are taken by value, so any reference must be wrapped with std::ref.
The return value is an identifier for the newly created thread. If there are insufficient resources for creating a new thread, then NullThread will be returned.
ThreadId Arachne::getThreadId ( )

Return a thread handle for the currently executing thread, identical to the one returned by the createThread call that initially created this thread.

When invoked from a non-Arachne thread, this function returns Arachne::NullThread.

void Arachne::init ( int *  argcp,
const char **  argv 

This function sets up state needed by the thread library, and must be invoked before any other function in the thread library is invoked. It is undefined behavior to invoke other Arachne functions before this one.

Arachne will take configuration options from the command line specified by argc and argv, and then update the values of argv and argc to reflect the remaining arguments.

Here are the current available options.

   The starting number of cores the application should use.
   The largest number of core the appliation may use
   The size of each user stack.
argcpThe pointer to argc, the number of arguments passed to the application. This pointer will be used to update argc after Arachne has consumed its arguments.
argvThe pointer to the command line argument array, which will be modiifed to remove the options that Arachne recognizes.
void Arachne::join ( ThreadId  id)

Block the current thread until the thread identified by id finishes its execution.

idThe id of the thread to join.
void Arachne::setErrorStream ( FILE *  stream)

Change the target of the error stream, allowing redirection to an application's log.

void Arachne::shutDown ( )

This call will cause all Arachne threads to terminate, and cause waitForTermination() to return.

It is typically used only for an application's unit tests, where the global teardown function in the unit test would call Arachne::shutDown() followed immediately by Arachne::waitForTermination().

This function can be called from any Arachne or non-Arachne thread.

void Arachne::signal ( ThreadId  id)

Make the thread referred to by ThreadId runnable. If one thread exits and another is created between the check and the setting of the wakeup flag, this signal will result in a spurious wake-up. If this method is invoked on a currently running thread, it will have the effect of causing the thread to immediately unblock the next time it blocks.

idThe id of the thread to signal.
void Arachne::sleep ( uint64_t  ns)

Sleep for at least ns nanoseconds. The amount of additional delay may be impacted by other threads' activities such as blocking and yielding.

void Arachne::testDestroy ( )

This function should be invoked in unit test teardown to clean up the state that makes Arachne functions callable from the unit test.

void Arachne::testInit ( )

This function should be invoked in unit test setup to make Arachne functions callable from the unit test, which is not an Arachne thread.

This function sets up just enough state to allow the current thread to execute unit tests which call Arachne functions. We assume that the unit tests are run from the main kernel thread which will never swap out when running the dispatch() loop.

void Arachne::waitForTermination ( )

This function must be called by the main application thread and will block until Arachne is terminated via a call to shutDown().

Upon termination, this function tears down all state created by init, and restores the state of the system to the time before init is called.

void Arachne::yield ( )

This method is used as part of cooperative multithreading to give other Arachne threads on the same core a chance to run. It will return when all other threads have had a chance to run.

Variable Documentation

const Arachne::ThreadId Arachne::NullThread

This value represents the non-existence of a thread and can be returned by any Arachne function that would normally return a ThreadId.

One example is createThread when there are not enough resources to create a new thread.