Arachne Public API

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

Functions
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)

Variables
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 ( )

inline

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.

Parameters

__f	The main function for the new thread.
__args	The 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.

Returns

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.

--numCores
   The starting number of cores the application should use.
--maxNumCores
   The largest number of core the appliation may use
--stackSize
   The size of each user stack.

Parameters

argcp	The 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.
argv	The 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.

Parameters

id	The 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.

Parameters

id	The 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.