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
[legend]
Collaboration diagram for uThread:
Collaboration graph
[legend]

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 uThread More...
 

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 {
  INITIALIZED, READY, RUNNING, YIELD,
  MIGRATE, WAITING, TERMINATED
}
 
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

ClustercurrentCluster
 
kThreadhomekThread
 
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
 

Friends

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

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

Create a uThread with a given stack size.

Parameters
ssstack size
joinableWhether this thread is joinable or detached
Returns
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)
inlinestatic

Create a uThread with default stack size.

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

Get a pointer to the current running uThread.

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

return the current Cluster uThread is executed on

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

get the ID of this uThread

Returns
ID of the uThread
static uint64_t uThread::getTotalNumberofUTs ( )
inlinestatic
Returns
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.

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

Move the uThread to the provided cluster.

Parameters
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 )
delete
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

Parameters
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 ( )
static

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

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: