User-level library to wrap thread-synch kernel-level functionalities. More...

#include <sys/types.h>
#include <sys/ioctl.h>
#include <sys/stat.h>
#include <unistd.h>
#include <stdio.h>
#include <stdlib.h>
#include <fcntl.h>
#include <string.h>
#include <stdbool.h>

Include dependency graph for thread_synch.h:

Go to the source code of this file.

Data Structures
struct	msg_t
	Basic structure to represent a message. More...

struct	group_t
	System-wide descriptor of a group. More...

struct	T_THREAD_SYNCH
	User-level handler of the thread-synch main device. More...

struct	T_THREAD_GROUP
	User-level handler of a group. More...

Macros
#define	_GNU_SOURCE 1

#define	ATTR_BUFF_SIZE 64

#define	DEVICE_NAME_SIZE 64

#define	GROUP_CLASS_NAME "group_synch"

#define	CLASS_NAME "thread_synch"

#define	D_DEV_NAME "main_thread_sync"

#define	D_DEV_MAJOR (0)

#define	D_DEV_MINOR (0)

#define	GRP_MIN_ID 0

#define	GRP_MAX_ID 255

#define	NO_MSG_PRESENT 1
	Errors code.

#define	ALLOC_ERR -2

#define	USER_COPY_ERR -3

#define	SEM_INIT_ERR -4 / @brief Semaphore initialization /

#define	MSG_INVALID_FORMAT -11

#define	MSG_SIZE_ERROR -12

#define	MEMORY_ERROR -13

#define	STORAGE_SIZE_ERR -14

#define	TS_NOT_FOUND -50

#define	TS_OPEN_ERR -51

#define	UNAUTHORIZED -52

#define	PERMISSION_ERR -53

#define	GROUP_CLOSED -54

#define	BUFF_SIZE 512

#define	POLL_TIMEOUT 5

#define	PARAM_NUMBER 3

#define	IOCTL_GET_GROUP_DESC _IOR('Q', 1, group_t*)
	ioctls

#define	IOCTL_SET_SEND_DELAY _IOW('Y', 0, long)

#define	IOCTL_REVOKE_DELAYED_MESSAGES _IO('Y', 1)

#define	IOCTL_CANCEL_DELAY _IO('Y', 2)

#define	IOCTL_SLEEP_ON_BARRIER _IO('Z', 0)

#define	IOCTL_AWAKE_BARRIER _IO('Z', 1)

#define	IOCTL_INSTALL_GROUP _IOW('X', 99, group_t*)

#define	IOCTL_GET_GROUP_ID _IOW('X', 100, group_t*)

#define	IOCTL_CHANGE_OWNER _IOW('Q', 102, uid_t)

#define	IOCTL_SET_STRICT_MODE _IOW('Q', 101, bool)

Functions
int	initThreadSyncher (thread_synch_t *main_syncher)
	Initialize a 'thread_synch_t' structure. More...

thread_group_t *	installGroup (const group_t group_descriptor, thread_synch_t *main_synch)
	Install a group in the system given a group descriptor. More...

int	readGroupInfo (thread_synch_t *main_syncher)

int	openGroup (thread_group_t *group)
	Open a group, the thread PID is added to group's active members. More...

int	readMessage (void buffer, size_t len, thread_group_t group)
	Read a message from a given group. More...

int	writeMessage (const void buffer, size_t len, thread_group_t group)
	Write a message in a given group. More...

int	setDelay (const long _delay, thread_group_t *group)
	Set the delay value for a given group. More...

int	revokeDelay (thread_group_t *group)
	Revoke all the delayed messaged on a given group and deliver it. More...

int	cancelDelay (thread_group_t *group)
	Deliver immediately all delayed messages. More...

int	sleepOnBarrier (thread_group_t *group)
	Put the process which call this function on sleep. More...

int	awakeBarrier (thread_group_t *group)
	Awake all the process present in a wait queue for a given group. More...

unsigned long	getCurrentStorageSize (thread_group_t *group)
	Get the current storage size value for a given group. More...

unsigned long	getMaxStorageSize (thread_group_t *group)
	Get the maximum storage size value for a given group. More...

unsigned long	getMaxMessageSize (thread_group_t *group)
	Get the maximum message size value for a given group. More...

int	setMaxMessageSize (thread_group_t *group, unsigned long val)
	Set the maximum message size value for a given group. More...

int	setMaxStorageSize (thread_group_t *group, unsigned long val)
	Set the maximum storage size value for a given group. More...

int	setGarbageCollectorRatio (thread_group_t *group, unsigned long val)
	Set the garbage collector ratio value for a given group. More...

int	includeStructureSize (thread_group_t *group, const bool value)
	Set a flag to count also supporting structure size in storage calculation. More...

int	enableStrictMode (thread_group_t *group)
	Enable strict mode on a group. More...

int	disableStrictMode (thread_group_t *group)
	Disable strict mode on a group. More...

int	changeOwner (thread_group_t *group, const uid_t new_owner)
	Change the owner of a group. More...

int	becomeOwner (thread_group_t *group)
	Change the owner of a group to the calling thread's UID. More...

thread_group_t *	loadGroupFromDescriptor (const group_t descriptor, thread_synch_t main_syncher)
	Load a group's structure given a group descriptor. More...

thread_group_t *	loadGroupFromID (const int group_id)
	Load a group structure given a group ID. More...

Detailed Description

User-level library to wrap thread-synch kernel-level functionalities.

Funcions will operate through two types of structures:

T_THREAD_SYNCH: handles request to the main synch device file
T_THREAD_GROUP: handles request to a group device file

Macro Definition Documentation

◆ CLASS_NAME

#define CLASS_NAME "thread_synch"

Main device class name

◆ D_DEV_MAJOR

#define D_DEV_MAJOR (0)

Main device major#

◆ D_DEV_MINOR

#define D_DEV_MINOR (0)

Main device minor#

◆ D_DEV_NAME

#define D_DEV_NAME "main_thread_sync"

Main device name

◆ DEVICE_NAME_SIZE

#define DEVICE_NAME_SIZE 64

Maximum device name lenght

◆ GRP_MAX_ID

#define GRP_MAX_ID 255

Group's max ID

◆ GRP_MIN_ID

#define GRP_MIN_ID 0

Group's min ID

Function Documentation

◆ awakeBarrier()

int awakeBarrier ( thread_group_t * group )

Awake all the process present in a wait queue for a given group.

Parameters

[in] *group T A pointer to an initialized group structure

Return values

-1	on error
0	on success
GROUP_CLOSED	if the provided group is closed

◆ becomeOwner()

int becomeOwner ( thread_group_t * group )

Change the owner of a group to the calling thread's UID.

Parameters

[in] *group A pointer to an initialized group structure

Return values

0	on success
UNAUTHORIZED	if the current user is not authorized to change the param
Negative	number on error

Note: If strict mode is enabled, only the current owner can set a new owner; If strict mode is enabled, any thread could change the group's owner

◆ cancelDelay()

int cancelDelay ( thread_group_t * group )

Deliver immediately all delayed messages.

When a group's device file is flushed (closed and opened) the driver will cancel the delay on all messages present on the delay queue

Parameters

[in] *group A pointer to a group's structure

Return values

0	on success (Legacy Version)
The	number of messages in which delay has been removed (Normal version)
GROUP_CLOSED	if the provided group structure is closed
negative	number on error (the number represent the 'errno' value)

◆ changeOwner()

int changeOwner	(	thread_group_t *	group,
		const uid_t	new_owner
	)

Change the owner of a group.

Parameters

[in] *group A pointer to an initialized group structure

Return values

0	on success
UNAUTHORIZED	if the current user is not authorized to change the param
GROUP_CLOSED	if the provided group is closed

Note: If strict mode is enabled, only the current owner can set a new owner; If strict mode is enabled, any thread could change the group's owner

◆ disableStrictMode()

int disableStrictMode ( thread_group_t * group )

Disable strict mode on a group.

Parameters

[in] *group A pointer to an initialized group structure

Return values

0	on success
UNAUTHORIZED	if the current user is not authorized to change the param
GROUP_CLOSED	if the provided group is closed

Note: If strict mode is enabled, only the owner can disable it

◆ enableStrictMode()

int enableStrictMode ( thread_group_t * group )

Enable strict mode on a group.

Parameters

[in] *group A pointer to an initialized group structure

Return values

0	on success
UNAUTHORIZED	if the current user is not authorized to change the param
GROUP_CLOSED	if the provided group is closed

Note: If strict mode is disabled, any threads can enable it through this function. If strict mode is enabled, only the owner can disable it

◆ getCurrentStorageSize()

unsigned long getCurrentStorageSize ( thread_group_t * group )

Get the current storage size value for a given group.

Parameters

[in] *group T A pointer to an initialized group structure

Bug:: Sometimes this function will return the incorrect value "0", when this happens a subsequent call of the function will return the correct value

Return values

The	value of the parameter
0	on error

◆ getMaxMessageSize()

unsigned long getMaxMessageSize ( thread_group_t * group )

Get the maximum message size value for a given group.

Parameters

[in] *group T A pointer to an initialized group structure

Return values

The	value of the parameter
0	on error

◆ getMaxStorageSize()

unsigned long getMaxStorageSize ( thread_group_t * group )

Get the maximum storage size value for a given group.

Parameters

[in] *group T A pointer to an initialized group structure

Return values

The	value of the parameter
0	on error

◆ includeStructureSize()

int includeStructureSize	(	thread_group_t *	group,
		const bool	value
	)

Set a flag to count also supporting structure size in storage calculation.

Parameters

[in]	*group	A pointer to an initialized group structure
[in]	value	The value the flag will be set to

Return values

0	on success
UNAUTHORIZED	if the current user is not authorized to change the param
GROUP_CLOSED	if the provided group is closed

Note: If strict mode is enabled, only the owner can disable it

◆ initThreadSyncher()

int initThreadSyncher ( thread_synch_t * main_syncher )

Initialize a 'thread_synch_t' structure.

Parameters

[out] main_syncher A pointer to the structure to initialize

Return values

TS_NOT_FOUND	if the main_syncher default file cannot be found
TS_OPEN_ERR	if there was an error while opening the main_syncher file
ALLOC_ERR	if there was an error during memory allocation
0	on success

◆ installGroup()

thread_group_t* installGroup	(	const group_t	group_descriptor,
		thread_synch_t *	main_synch
	)

Install a group in the system given a group descriptor.

Parameters

[in]	group_descriptor	The new group's descriptor
[in]	main_synch	A pointer to an initialized main_sych structure

Return values

A	pointer to a group structure
NULL	on error

◆ loadGroupFromDescriptor()

thread_group_t* loadGroupFromDescriptor	(	const group_t *	descriptor,
		thread_synch_t *	main_syncher
	)

Load a group's structure given a group descriptor.

Parameters

[in]	*descriptor	The descritor of the group to load
[in]	*main_syncher	Pointer to a thread_synch_t main structure

Return values

A	pointer to the group structure of the specified group
NULL	on error

Note: The provided group structure is not opened by default

◆ loadGroupFromID()

thread_group_t* loadGroupFromID ( const int group_id )

Load a group structure given a group ID.

Parameters

group_id The group ID

Return values

A	pointer to the group structure of the specified group
NULL	on error

Note: On success, the group is not opened

Bug:: The group's descriptor is not loaded, thus the diplayed name will appear as "(null)"

◆ openGroup()

int openGroup ( thread_group_t * group )

Open a group, the thread PID is added to group's active members.

Return values

0	on success
PERMISSION_ERR	on permission Error
negative	number on error

◆ readMessage()

int readMessage	(	void *	buffer,
		size_t	len,
		thread_group_t *	group
	)

Read a message from a given group.

Parameters

[out]	buffer	The buffer where the readed message is stored
[in]	len	The number of bytes to read
[in]	group	A pointer to the group's structure where the msg is readed

Return values

NO_MSG_PRESENT	if there is no message available
GROUP_CLOSED	if the provided group is closed
negative	number on error
0	on success

Note: Even if the parameter 'len' is less the the size of the actual message, the message is considered delivered and thus removed from the queue

◆ revokeDelay()

int revokeDelay ( thread_group_t * group )

Revoke all the delayed messaged on a given group and deliver it.

Parameters

[in] *group A pointer to an initialized group structure

Return values

Negative	number on error
The	number of revoked messages on success (>= 0)
GROUP_CLOSED	if the provided group is closed

◆ setDelay()

int setDelay	(	const long	_delay,
		thread_group_t *	group
	)

Set the delay value for a given group.

Parameters

[in]	_delay	The new delay value
[in]	*group	A pointer to an initialized group structure

Return values

-1	on error
0	on success
GROUP_CLOSED	if the provided group is closed

◆ setGarbageCollectorRatio()

int setGarbageCollectorRatio	(	thread_group_t *	group,
		const unsigned long	val
	)

Set the garbage collector ratio value for a given group.

Parameters

[in]	*group	A pointer to an initialized group structure
[in]	val	The new value of the parameter

Return values

-1	on error
GROUP_CLOSED	if the provided group is closed
0	on success

◆ setMaxMessageSize()

int setMaxMessageSize	(	thread_group_t *	group,
		const unsigned long	val
	)

Set the maximum message size value for a given group.

Parameters

[in]	*group	A pointer to an initialized group structure
[in]	val	The new value of the parameter

Return values

-1	on error
0	on success
GROUP_CLOSED	if the provided group is closed

◆ setMaxStorageSize()

int setMaxStorageSize	(	thread_group_t *	group,
		const unsigned long	val
	)

Set the maximum storage size value for a given group.

Parameters

[in]	*group	A pointer to an initialized group structure
[in]	val	The new value of the parameter

Return values

-1	on error
0	on success
GROUP_CLOSED	if the provided group is closed

◆ sleepOnBarrier()

int sleepOnBarrier ( thread_group_t * group )

Put the process which call this function on sleep.

Parameters

[in] *group T A pointer to an initialized group structure

Return values

Negative	number on error
0	on success
GROUP_CLOSED	if the provided group is closed

◆ writeMessage()

int writeMessage	(	const void *	buffer,
		size_t	len,
		thread_group_t *	group
	)

Write a message in a given group.

Parameters

[in]	buffer	The buffer that contains the message to write
[in]	len	The number of bytes to write
[in]	group	A pointer to the group's structure where the msg is written

Return values

negative	number on error
The	number of written bytes on successs
GROUP_CLOSED	if the provided group is closed

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ CLASS_NAME

◆ D_DEV_MAJOR

◆ D_DEV_MINOR

◆ D_DEV_NAME

◆ DEVICE_NAME_SIZE

◆ GRP_MAX_ID

◆ GRP_MIN_ID

Function Documentation

◆ awakeBarrier()

◆ becomeOwner()

◆ cancelDelay()

◆ changeOwner()

◆ disableStrictMode()

◆ enableStrictMode()

◆ getCurrentStorageSize()

◆ getMaxMessageSize()

◆ getMaxStorageSize()

◆ includeStructureSize()

◆ initThreadSyncher()

◆ installGroup()

◆ loadGroupFromDescriptor()

◆ loadGroupFromID()

◆ openGroup()

◆ readMessage()

◆ revokeDelay()

◆ setDelay()

◆ setGarbageCollectorRatio()

◆ setMaxMessageSize()

◆ setMaxStorageSize()

◆ sleepOnBarrier()

◆ writeMessage()