uThreads  0.3.0
Public Member Functions | Static Public Member Functions | Protected Types | Protected Member Functions | Static Protected Member Functions | Protected Attributes | Static Protected Attributes | Friends | List of all members
uThread Class Reference

user-level threads (fiber) More...

#include <uThread.h>

Inheritance diagram for uThread:
Inheritance graph
Collaboration diagram for uThread:
Collaboration graph

Public Member Functions

 uThread (const uThread &)=delete
 uThread cannot be copied or assigned
const uThreadoperator= (const uThread &)=delete
void start (const Cluster &cluster, ptr_t func, ptr_t arg1=nullptr, ptr_t arg2=nullptr, ptr_t arg3=nullptr)
 start the uThread by calling the function passed to it More...
void resume ()
 Resumes the uThread. If uThread is blocked or is waiting on IO it will be placed back on the ReadyQueue.
bool join ()
 Wait for uThread to finish execution and exit. More...
void detach ()
 Detach a joinable thread.
ClustergetCurrentCluster () const
 return the current Cluster uThread is executed on More...
uint64_t getID () const
 get the ID of this uTh

Static Public Member Functions

static uThreadcreate (size_t ss, bool joinable=false)
 Create a uThread with a given stack size. More...
static uThreadcreate (bool joinable=false)
 Create a uThread with default stack size. More...
static void yield ()
 Causes uThread to yield. More...
static void terminate ()
 Terminates the uThread. More...
static void migrate (Cluster *)
 Move the uThread to the provided cluster. More...
static uint64_t getTotalNumberofUTs ()
static uThreadcurrentUThread ()
 Get a pointer to the current running uThread. More...

Protected Types

enum  State : std::uint8_t {
enum  JState : std::uint8_t { DETACHED, JOINABLE, JOINING }

Protected Member Functions

 uThread (vaddr sb, size_t ss)
virtual void destory (bool)
void reset ()
void suspend (funcvoid2_t, void *)

Static Protected Member Functions

static vaddr createStack (size_t)
static void invoke (funcvoid3_t, ptr_t, ptr_t, ptr_t) __noreturn

Protected Attributes

vaddr stackPointer
vaddr stackBottom
size_t stackSize
UTVar * utvar
uint64_t uThreadID
enum uThread::State state
enum uThread::JState jState

Static Protected Attributes

static uThreadCache utCache
static std::atomic_ulong totalNumberofUTs
static std::atomic_ulong uThreadMasterID


class uThreadCache
class kThread
class Cluster
class BlockingQueue
class IOHandler
class Scheduler

Detailed Description

user-level threads (fiber)

uThreads are building blocks of this library. They are lightweight threads and do not have the same context switch overhead as kernel threads. Each uThread is an execution unit provided to run small tasks. uThreads are being managed cooperatively and there is no preemption involved. uThreads either yield, migrate, or blocked and giving way to other uThreads to get a chance to run.

Due to the cooperative nature of uThreads, it is recommended that uThreads do not block the underlying kernel thread for a long time. However, since there can be multiple kernel threads (kThread) in the program, if one or more uThreads block underlying kThreads for small amount of time the execution of the program does not stop and other kThreads keep executing.

Another pitfall can be when all uThreads are blocked and each waiting for an event to occurs which can cause deadlocks. It is programmer's responsibility to make sure this never happens. Although it never happens unless a uThread is blocked without a reason (not waiting on a lock or IO), otherwise there is always an event (another uThread or polling structure) that unblock the uThread.

Each uThread has its own stack which is very smaller than kernel thread's stack. This stack is allocated when uThread is created.

Constructor & Destructor Documentation

uThread::uThread ( vaddr  sb,
size_t  ss 

The main and only constructor for uThread. uThreads are not supposed to be created by using the constructor. The memory used to save the uThread object is allocated at the beginning of its own stack. Thus, by freeing the stack memory uThread object is being destroyed as well. Therefore, the implicit destructor is not necessary.

Member Function Documentation

uThread * uThread::create ( size_t  ss,
bool  joinable = false 

Create a uThread with a given stack size.

ssstack size
joinableWhether this thread is joinable or detached
a pointer to a new uThread

This function relies on a uThreadCache structure and does not always allocate the stack.

static uThread* uThread::create ( bool  joinable = false)

Create a uThread with default stack size.

joinableWhether this thread is joinable or detached
a pointer to a new uThread
uThread * uThread::currentUThread ( )

Get a pointer to the current running uThread.

pointer to the current uThread
Cluster& uThread::getCurrentCluster ( ) const

return the current Cluster uThread is executed on

the current Cluster uThread is executed on
uint64_t uThread::getID ( ) const

get the ID of this uThread

ID of the uThread
static uint64_t uThread::getTotalNumberofUTs ( )
Total number of uThreads in the program

This number does not include mainUT or IOUTs

bool uThread::join ( )

Wait for uThread to finish execution and exit.

Whether join was successful or failed
void uThread::migrate ( Cluster cluster)

Move the uThread to the provided cluster.

clusterThis function is used to migrate the uThread to another Cluster. Migration is useful specially if clusters form a pipeline of execution.
const uThread& uThread::operator= ( const uThread )
void uThread::start ( const Cluster cluster,
ptr_t  func,
ptr_t  arg1 = nullptr,
ptr_t  arg2 = nullptr,
ptr_t  arg3 = nullptr 

start the uThread by calling the function passed to it

clusterThe cluster that function belongs to.
funca pointer to a function that should be executed by the uThread.
arg1first argument of the function (can be nullptr)
arg2second argument of the function (can be nullptr)
arg3third argument of the function (can be nullptr)

After creating the uThread and allocating the stack, the start() function should be called to get the uThread going.

void uThread::terminate ( )

Terminates the uThread.

By calling this function uThread is being terminated and uThread object is either destroyed or put back into the cache.

void uThread::yield ( )

Causes uThread to yield.

uThread give up the execution context and place itself back on the ReadyQueue of the Cluster. If there is no other uThreads available to switch to, the current uThread continues execution.

The documentation for this class was generated from the following files: