C Wrapper for uThreads. More...

#include <pthread.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <inttypes.h>
#include <stdbool.h>

Include dependency graph for cwrapper.h:

Go to the source code of this file.

Cluster
C interface for class Cluster.
typedef struct WCluster	WCluster

WCluster *	cluster_create ()

void	cluster_destroy (WCluster *cluster)

WCluster *	cluster_get_default ()

WCluster *	cluster_get_current ()

uint64_t	cluster_get_id (WCluster *cluster)
	Get the ID of Cluster. More...

size_t	cluster_get_number_of_kThreads (WCluster *cluster)
	Total number of kThreads belonging to this cluster. More...

kThread
C interface for class kThread.
typedef struct WkThread	WkThread

WkThread *	kThread_create (WCluster *cluster)

void	kThread_destroy (WkThread *kt)

uint64_t	kThread_get_total_number_of_kThreads ()

WkThread *	kThread_get_current ()
	Get the pointer to the current kThread. More...

pthread_t	kThread_get_current_pthread_id ()
	return the native hanlde for the kernel thread More...

pthread_t	kThread_get_pthread_id (WkThread *kt)
	return the native hanlde for the kernel thread More...

uThread
C interface for class uThread.
typedef struct WuThread	WuThread

WuThread *	uThread_create (bool joinable)
	Create a uThread with a given stack size. More...

void	uThread_start (WuThread ut, WCluster cluster, void func, void arg1, void arg2, void arg3)
	start the uThread by calling the function passed to it More...

void	uThread_migrate (WCluster *cluster)
	Move the uThread to the provided cluster. More...

void	uThread_terminate (WuThread *ut)
	Terminates the uThread. More...

void	uThread_yield ()
	Causes uThread to yield. More...

bool	uThread_join (WuThread *ut)
	Wait for uThread to finish execution and exit. More...

void	uThread_detach (WuThread *ut)
	Detach a joinable thread. More...

uint64_t	uThread_get_id (WuThread *ut)
	get the ID of this uThread More...

WuThread *	uThread_get_current ()
	Get a pointer to the current running uThread. More...

uint64_t	uThread_get_total_number_of_uThreads ()

Connection
C interface for class Connection.
typedef struct WConnection	WConnection

WConnection *	connection_create ()
	Create a Connection that does not have. More...

WConnection *	connection_create_with_fd (int fd)
	Create a connection object with the provided fd. More...

WConnection *	connection_create_socket (int domain, int type, int protocol)
	Same as socket syscall adds \| SOCK_NONBLOCK to type. More...

void	connection_destroy (WConnection *c)

int	connection_accept (WConnection acceptor, WConnection conn, struct sockaddr addr, socklen_t addrlen)
	nonblocking accept syscall and updating the passed Connection object More...

WConnection *	connection_accept_connenction (WConnection acceptor, struct sockaddr addr, socklen_t *addrlen)
	Accepts a connection and returns a connection object. More...

int	connection_socket (WConnection *conn, int domain, int type, int protocol)
	Same as socket syscall, set the fd for current connection. More...

int	connection_listen (WConnection *conn, int backlog)
	Same as listen syscall on current fd. More...

int	connection_bind (WConnection conn, const struct sockaddr addr, socklen_t addrlen)
	Same as bind syscall. More...

int	connection_connect (WConnection conn, const struct sockaddr addr, socklen_t addrlen)
	Same as connect syscall. More...

int	connection_close (WConnection *conn)
	closes the socket More...

ssize_t	connection_recv (WConnection conn, void buf, size_t len, int flags)
	Call the underlying system call on Connection's file descriptor. More...

ssize_t	connection_recvfrom (WConnection conn, void buf, size_t len, int flags, struct sockaddr src_addr, socklen_t addrlen)
	Call the underlying system call on Connection's file descriptor. More...

ssize_t	connection_recvmsg (WConnection conn, int sockfd, struct msghdr msg, int flags)
	Call the underlying system call on Connection's file descriptor. More...

int	connection_recvmmsg (WConnection conn, int sockfd, struct mmsghdr msgvec, unsigned int vlen, unsigned int flags, struct timespec *timeout)
	Call the underlying system call on Connection's file descriptor. More...

ssize_t	connection_send (WConnection conn, const void buf, size_t len, int flags)
	Call the underlying system call on Connection's file descriptor. More...

ssize_t	connection_sendto (WConnection conn, int sockfd, const void buf, size_t len, int flags, const struct sockaddr *dest_addr, socklen_t addrlen)
	Call the underlying system call on Connection's file descriptor. More...

ssize_t	connection_sendmsg (WConnection conn, const struct msghdr msg, int flags)
	Call the underlying system call on Connection's file descriptor. More...

int	connection_sendmmsg (WConnection conn, int sockfd, struct mmsghdr msgvec, unsigned int vlen, unsigned int flags)
	Call the underlying system call on Connection's file descriptor. More...

ssize_t	connection_read (WConnection conn, void buf, size_t count)
	Call the underlying system call on Connection's file descriptor. More...

ssize_t	connection_write (WConnection conn, const void buf, size_t count)
	Call the underlying system call on Connection's file descriptor. More...

void	connection_block_on_read (WConnection *conn)
	Block uThread, waiting for fd to become ready for read. More...

void	connection_block_on_write (WConnection *conn)
	Block uThread, waiting for fd to become ready for write. More...

int	connection_get_fd (WConnection *conn)

Mutex
C interface for class Mutex.
typedef struct WMutex	WMutex

WMutex *	mutex_create ()

void	mutex_destroy (WMutex *mutex)

bool	mutex_acquire (WMutex *mutex)
	acquire the mutex More...

void	mutex_release (WMutex *mutex)
	release the Mutex More...

OwnerLock
C interface for class OwnerLock.
typedef struct WOwnerLock	WOwnerLock

WOwnerLock *	ownerlock_create ()

void	ownerlock_destroy (WOwnerLock *olock)

uint64_t	ownerlock_acquire (WOwnerLock *olock)

void	ownerlock_release (WOwnerLock *olock)

ConditionVariable
C interface for class ConditionVariable.
typedef struct WConditionVariable	WConditionVariable

WConditionVariable *	condition_variable_create ()

void	condition_variable_destroy (WConditionVariable *cv)

void	condition_variable_wait (WConditionVariable cv, WMutex mutex)
	Block uThread on the condition variable using the provided mutex. More...

void	condition_variable_signal (WConditionVariable cv, WMutex mutex)
	Unblock one uThread waiting on the condition variable. More...

void	condition_variable_signall_all (WConditionVariable cv, WMutex mutex)
	unblock all uThreads waiting on the condition variable More...

bool	condition_variable_empty (WConditionVariable *cv)
	Whether the waiting list is empty or not. More...

Semaphore
C interface for class Semaphore.
typedef struct WSemaphore	WSemaphore

WSemaphore *	semaphore_create ()
	Create a new Semaphore. More...

void	semaphore_destroy (WSemaphore *sem)

bool	semaphore_p (WSemaphore *sem)
	Decrement the value of the Semaphore. More...

void	semaphore_v (WSemaphore *sem)
	increment the value of the Semaphore More...

uThreadPool
C interface for class uThreadPool.
typedef struct WuThreadPool	WuThreadPool

WuThreadPool *	uthreadpool_create ()

void	uthreadpool_destory (WuThreadPool *utp)

void	uthreadpool_execute (WuThreadPool utp, WCluster cluster, void (start_routine)(void ), void arg)

Detailed Description

C Wrapper for uThreads.

Author: Saman Barghi

Function Documentation

WCluster* cluster_create ( )

Create a new Cluster

void cluster_destroy ( WCluster * cluster )

WCluster* cluster_get_current ( )

WCluster* cluster_get_default ( )

Returns: defaultCluster

uint64_t cluster_get_id ( WCluster * cluster )

Get the ID of Cluster.

Returns: The ID of the cluster

size_t cluster_get_number_of_kThreads ( WCluster * cluster )

Total number of kThreads belonging to this cluster.

Returns: Total number of kThreads belonging to this cluster

WConditionVariable* condition_variable_create ( )

void condition_variable_destroy ( WConditionVariable * cv )

bool condition_variable_empty ( WConditionVariable * cv )

Whether the waiting list is empty or not.

Returns: Whether the waiting list is empty or not

void condition_variable_signal	(	WConditionVariable *	cv,
		WMutex *	mutex
	)

Unblock one uThread waiting on the condition variable.

Parameters

mutex The mutex to be released after unblocking is done

void condition_variable_signall_all	(	WConditionVariable *	cv,
		WMutex *	mutex
	)

unblock all uThreads waiting on the condition variable

Parameters

mutex The mutex to be released after unblocking is done

void condition_variable_wait	(	WConditionVariable *	cv,
		WMutex *	mutex
	)

Block uThread on the condition variable using the provided mutex.

Parameters

mutex used to synchronize access to the condition

int connection_accept	(	WConnection *	acceptor,
		WConnection *	conn,
		struct sockaddr *	addr,
		socklen_t *	addrlen
	)

nonblocking accept syscall and updating the passed Connection object

Parameters

conn	Pointer to a Connection object that is not initialized

Returns: same as accept system call

This format is used for compatibility with C

WConnection* connection_accept_connenction	(	WConnection *	acceptor,
		struct sockaddr *	addr,
		socklen_t *	addrlen
	)

Accepts a connection and returns a connection object.

Returns: Newly created connection

Throws a std::system_error exception on error. Never call from C.

int connection_bind	(	WConnection *	conn,
		const struct sockaddr *	addr,
		socklen_t	addrlen
	)

Same as bind syscall.

Returns: Same as bind syscall

void connection_block_on_read ( WConnection * conn )

Block uThread, waiting for fd to become ready for read.

void connection_block_on_write ( WConnection * conn )

Block uThread, waiting for fd to become ready for write.

int connection_close ( WConnection * conn )

closes the socket

Returns: the same as close system call

int connection_connect	(	WConnection *	conn,
		const struct sockaddr *	addr,
		socklen_t	addrlen
	)

Same as connect syscall.

Returns: Same as connect syscall

WConnection* connection_create ( )

Create a Connection that does not have.

This is useful for accept or socket functions that require a Connection object without fd being set

WConnection* connection_create_socket	(	int	domain,
		int	type,
		int	protocol
	)

Same as socket syscall adds | SOCK_NONBLOCK to type.

Returns: same as socket syscall

Throws a std::system_error exception. Do not call from C code. The unerlying socket is always nonbelocking. This is achieved by adding a (| SOCK_NONBLOCK) to type, thus requires linux kernels > 2.6.27

WConnection* connection_create_with_fd ( int fd )

Create a connection object with the provided fd.

Parameters

fd	If the connection is already established by other means, set the fd and add it to the polling structure

void connection_destroy ( WConnection * c )

int connection_get_fd ( WConnection * conn )

int connection_listen	(	WConnection *	conn,
		int	backlog
	)

Same as listen syscall on current fd.

Returns: Same as listen syscall

ssize_t connection_read	(	WConnection *	conn,
		void *	buf,
		size_t	count
	)

Call the underlying system call on Connection's file descriptor.

Returns: Same as what the related systemcall returns

This function calls the system call with the same name. If the socket is ready for the required function it returns immediately, otherwise it blocks in the user-level (blocks uThread not kThread), and polls the file descriptor until it becomes ready.

The return results is the same as the underlying system call except that the following condition is never true when the function returns: (res == -1) && (errno == EAGAIN || errno == EWOULDBLOCK)

which means the Connection object does the polling and only returns when an error occurs or the socket is ready.

ssize_t connection_recv	(	WConnection *	conn,
		void *	buf,
		size_t	len,
		int	flags
	)

Call the underlying system call on Connection's file descriptor.

Returns: Same as what the related systemcall returns

This function calls the system call with the same name. If the socket is ready for the required function it returns immediately, otherwise it blocks in the user-level (blocks uThread not kThread), and polls the file descriptor until it becomes ready.

The return results is the same as the underlying system call except that the following condition is never true when the function returns: (res == -1) && (errno == EAGAIN || errno == EWOULDBLOCK)

which means the Connection object does the polling and only returns when an error occurs or the socket is ready.

ssize_t connection_recvfrom	(	WConnection *	conn,
		void *	buf,
		size_t	len,
		int	flags,
		struct sockaddr *	src_addr,
		socklen_t *	addrlen
	)

Call the underlying system call on Connection's file descriptor.

Returns: Same as what the related systemcall returns

This function calls the system call with the same name. If the socket is ready for the required function it returns immediately, otherwise it blocks in the user-level (blocks uThread not kThread), and polls the file descriptor until it becomes ready.

The return results is the same as the underlying system call except that the following condition is never true when the function returns: (res == -1) && (errno == EAGAIN || errno == EWOULDBLOCK)

which means the Connection object does the polling and only returns when an error occurs or the socket is ready.

int connection_recvmmsg	(	WConnection *	conn,
		int	sockfd,
		struct mmsghdr *	msgvec,
		unsigned int	vlen,
		unsigned int	flags,
		struct timespec *	timeout
	)

Call the underlying system call on Connection's file descriptor.

Returns: Same as what the related systemcall returns

This function calls the system call with the same name. If the socket is ready for the required function it returns immediately, otherwise it blocks in the user-level (blocks uThread not kThread), and polls the file descriptor until it becomes ready.

The return results is the same as the underlying system call except that the following condition is never true when the function returns: (res == -1) && (errno == EAGAIN || errno == EWOULDBLOCK)

which means the Connection object does the polling and only returns when an error occurs or the socket is ready.

ssize_t connection_recvmsg	(	WConnection *	conn,
		int	sockfd,
		struct msghdr *	msg,
		int	flags
	)

Call the underlying system call on Connection's file descriptor.

Returns: Same as what the related systemcall returns

This function calls the system call with the same name. If the socket is ready for the required function it returns immediately, otherwise it blocks in the user-level (blocks uThread not kThread), and polls the file descriptor until it becomes ready.

The return results is the same as the underlying system call except that the following condition is never true when the function returns: (res == -1) && (errno == EAGAIN || errno == EWOULDBLOCK)

which means the Connection object does the polling and only returns when an error occurs or the socket is ready.

ssize_t connection_send	(	WConnection *	conn,
		const void *	buf,
		size_t	len,
		int	flags
	)

Call the underlying system call on Connection's file descriptor.

Returns: Same as what the related systemcall returns

This function calls the system call with the same name. If the socket is ready for the required function it returns immediately, otherwise it blocks in the user-level (blocks uThread not kThread), and polls the file descriptor until it becomes ready.

The return results is the same as the underlying system call except that the following condition is never true when the function returns: (res == -1) && (errno == EAGAIN || errno == EWOULDBLOCK)

which means the Connection object does the polling and only returns when an error occurs or the socket is ready.

int connection_sendmmsg	(	WConnection *	conn,
		int	sockfd,
		struct mmsghdr *	msgvec,
		unsigned int	vlen,
		unsigned int	flags
	)

Call the underlying system call on Connection's file descriptor.

Returns: Same as what the related systemcall returns

This function calls the system call with the same name. If the socket is ready for the required function it returns immediately, otherwise it blocks in the user-level (blocks uThread not kThread), and polls the file descriptor until it becomes ready.

The return results is the same as the underlying system call except that the following condition is never true when the function returns: (res == -1) && (errno == EAGAIN || errno == EWOULDBLOCK)

which means the Connection object does the polling and only returns when an error occurs or the socket is ready.

ssize_t connection_sendmsg	(	WConnection *	conn,
		const struct msghdr *	msg,
		int	flags
	)

Call the underlying system call on Connection's file descriptor.

Returns: Same as what the related systemcall returns

This function calls the system call with the same name. If the socket is ready for the required function it returns immediately, otherwise it blocks in the user-level (blocks uThread not kThread), and polls the file descriptor until it becomes ready.

The return results is the same as the underlying system call except that the following condition is never true when the function returns: (res == -1) && (errno == EAGAIN || errno == EWOULDBLOCK)

which means the Connection object does the polling and only returns when an error occurs or the socket is ready.

ssize_t connection_sendto	(	WConnection *	conn,
		int	sockfd,
		const void *	buf,
		size_t	len,
		int	flags,
		const struct sockaddr *	dest_addr,
		socklen_t	addrlen
	)

Call the underlying system call on Connection's file descriptor.

Returns: Same as what the related systemcall returns

This function calls the system call with the same name. If the socket is ready for the required function it returns immediately, otherwise it blocks in the user-level (blocks uThread not kThread), and polls the file descriptor until it becomes ready.

The return results is the same as the underlying system call except that the following condition is never true when the function returns: (res == -1) && (errno == EAGAIN || errno == EWOULDBLOCK)

which means the Connection object does the polling and only returns when an error occurs or the socket is ready.

int connection_socket	(	WConnection *	conn,
		int	domain,
		int	type,
		int	protocol
	)

Same as socket syscall, set the fd for current connection.

Returns: same as socket syscall The unerlying socket is always nonbelocking. This is achieved by adding a (| SOCK_NONBLOCK) to type, thus requires linux kernels > 2.6.27

ssize_t connection_write	(	WConnection *	conn,
		const void *	buf,
		size_t	count
	)

Call the underlying system call on Connection's file descriptor.

Returns: Same as what the related systemcall returns

This function calls the system call with the same name. If the socket is ready for the required function it returns immediately, otherwise it blocks in the user-level (blocks uThread not kThread), and polls the file descriptor until it becomes ready.

The return results is the same as the underlying system call except that the following condition is never true when the function returns: (res == -1) && (errno == EAGAIN || errno == EWOULDBLOCK)

which means the Connection object does the polling and only returns when an error occurs or the socket is ready.

WkThread* kThread_create ( WCluster * cluster )

void kThread_destroy ( WkThread * kt )

WkThread* kThread_get_current ( )

Get the pointer to the current kThread.

Returns: current kThread

This is necessary when a uThread wants to find which kThread it is being executed over.

pthread_t kThread_get_current_pthread_id ( )

return the native hanlde for the kernel thread

Returns: native handle for the kThread

In linux this is pthread_t representation of the thread.

pthread_t kThread_get_pthread_id ( WkThread * kt )

return the native hanlde for the kernel thread

Returns: native handle for the kThread

In linux this is pthread_t representation of the thread.

uint64_t kThread_get_total_number_of_kThreads ( )

Returns: total number of kThreads running under the program.

bool mutex_acquire ( WMutex * mutex )

acquire the mutex

Returns: true if it was acquired, false otherwise

The return value is only for when timeouts are implemented

WMutex* mutex_create ( )

void mutex_destroy ( WMutex * mutex )

void mutex_release ( WMutex * mutex )

release the Mutex

uint64_t ownerlock_acquire ( WOwnerLock * olock )

WOwnerLock* ownerlock_create ( )

void ownerlock_destroy ( WOwnerLock * olock )

void ownerlock_release ( WOwnerLock * olock )

WSemaphore* semaphore_create ( )

Create a new Semaphore.

Parameters

c	Initial value of the Semaphore

void semaphore_destroy ( WSemaphore * sem )

bool semaphore_p ( WSemaphore * sem )

Decrement the value of the Semaphore.

Returns: Whether it was successful or not

void semaphore_v ( WSemaphore * sem )

increment the value of the Semaphore

WuThread* uThread_create ( bool joinable )

Create a uThread with a given stack size.

Parameters

ss	stack size
joinable	Whether 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.

void uThread_detach ( WuThread * ut )

Detach a joinable thread.

WuThread* uThread_get_current ( )

Get a pointer to the current running uThread.

Returns: pointer to the current uThread

uint64_t uThread_get_id ( WuThread * ut )

get the ID of this uThread

Returns: ID of the uThread

uint64_t uThread_get_total_number_of_uThreads ( )

Returns: Total number of uThreads in the program

This number does not include mainUT or IOUTs

bool uThread_join ( WuThread * ut )

Wait for uThread to finish execution and exit.

Returns: Whether join was successful or failed

void uThread_migrate ( WCluster * cluster )

Move the uThread to the provided cluster.

Parameters

cluster This function is used to migrate the uThread to another Cluster. Migration is useful specially if clusters form a pipeline of execution.

void uThread_start	(	WuThread *	ut,
		WCluster *	cluster,
		void *	func,
		void *	arg1,
		void *	arg2,
		void *	arg3
	)

start the uThread by calling the function passed to it

Parameters

cluster	The cluster that function belongs to.
func	a pointer to a function that should be executed by the uThread.
arg1	first argument of the function (can be nullptr)
arg2	second argument of the function (can be nullptr)
arg3	third 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 ( WuThread * ut )

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.

Cluster

kThread

uThread

Connection

Mutex

OwnerLock

ConditionVariable

Semaphore

uThreadPool

Detailed Description

Function Documentation