Inter-Thread Communication

Collaboration diagram for Inter-Thread Communication:

Modules
	Semaphore
	Mutex
	Event
	Mailbox
	Messagequeue

Data Structures
struct	rt_ipc_object

Macros
#define	RT_IPC_FLAG_FIFO   0x00
#define	RT_IPC_FLAG_PRIO   0x01
#define	RT_IPC_CMD_UNKNOWN   0x00
#define	RT_IPC_CMD_RESET   0x01
#define	RT_IPC_CMD_GET_STATE   0x02
#define	RT_IPC_CMD_SET_VLIMIT   0x03
#define	RT_WAITING_FOREVER   -1
#define	RT_WAITING_NO   0

Functions
rt_inline rt_err_t	_ipc_object_init (struct rt_ipc_object *ipc)
struct rt_thread *	rt_susp_list_dequeue (rt_list_t *susp_list, rt_err_t thread_error)
rt_err_t	rt_susp_list_resume_all (rt_list_t *susp_list, rt_err_t thread_error)
rt_err_t	rt_susp_list_resume_all_irq (rt_list_t *susp_list, rt_err_t thread_error, struct rt_spinlock *lock)
rt_err_t	rt_susp_list_enqueue (rt_list_t *susp_list, rt_thread_t thread, int ipc_flags)
void	rt_susp_list_print (rt_list_t *list)
rt_err_t	rt_thread_suspend_to_list (rt_thread_t thread, rt_list_t *susp_list, int ipc_flags, int suspend_flag)
void	rt_thread_defunct_enqueue (rt_thread_t thread)
rt_thread_t	rt_thread_defunct_dequeue (void)
void	rt_spin_lock_init (struct rt_spinlock *lock)
void	rt_spin_lock (struct rt_spinlock *lock)
void	rt_spin_unlock (struct rt_spinlock *lock)
rt_base_t	rt_spin_lock_irqsave (struct rt_spinlock *lock)
void	rt_spin_unlock_irqrestore (struct rt_spinlock *lock, rt_base_t level)

Detailed Description

inter-thread communication

RT-Thread operating system supports the traditional semaphore and mutex.

• Mutex objects use inherited priority to prevent priority reversion.
• The semaphore release action is safe for interrupt service routine.

Moreover, the blocked queue for thread to obtain semaphore or mutex can be sorted by priority or FIFO. There are two flags to indicate this mechanism.

• RT_IPC_FLAG_FIFO when the resource is available, thread pended on this resource at first would get the resource.
• RT_IPC_FLAG_PRIO when the resource is available, thread pended on this resource who had the most high priority would get the resource.

RT-Thread operating systems supports event/fast event, mail box and message queue.

• The event mechanism is used to awake a thread by setting one or more corresponding bit of a binary number when an event ocurs.
• The fast event supports event thread queue. Once a one bit event occurs, the corresponding blocked thread can be found out timing accurately, then will be waked up.
• In mailbox, the mail length is fixed to 4 byte, which is more effective than message queue.
• The send action for communication facilities is also safe for interrupt service routine.

Macro Definition Documentation

RT_IPC_FLAG_FIFO

#define RT_IPC_FLAG_FIFO   0x00

IPC flags and control command definitions FIFOed IPC. Inter-Thread Communication.

RT_IPC_FLAG_PRIO

#define RT_IPC_FLAG_PRIO   0x01

PRIOed IPC. Inter-Thread Communication.

RT_IPC_CMD_UNKNOWN

#define RT_IPC_CMD_UNKNOWN   0x00

unknown IPC command

RT_IPC_CMD_RESET

#define RT_IPC_CMD_RESET   0x01

reset IPC object

RT_IPC_CMD_GET_STATE

#define RT_IPC_CMD_GET_STATE   0x02

get the state of IPC object

RT_IPC_CMD_SET_VLIMIT

#define RT_IPC_CMD_SET_VLIMIT   0x03

set max limit value of IPC value

RT_WAITING_FOREVER

#define RT_WAITING_FOREVER   -1

Block forever until get resource.

RT_WAITING_NO

#define RT_WAITING_NO   0

Non-block.

Function Documentation

_ipc_object_init()

rt_inline rt_err_t _ipc_object_init

(

struct rt_ipc_object *

ipc

)

This function will initialize an IPC object, such as semaphore, mutex, messagequeue and mailbox.

Note

Executing this function will complete an initialization of the suspend thread list of the ipc object.

Parameters

ipc	is a pointer to the IPC object.

Returns

Return the operation status. When the return value is RT_EOK, the initialization is successful. When the return value is any other values, it means the initialization failed.

Warning

This function can be called from all IPC initialization and creation.

rt_susp_list_dequeue()

struct rt_thread * rt_susp_list_dequeue	(	rt_list_t *	susp_list,
		rt_err_t	thread_error
	)

Dequeue a thread from suspended list and set it to ready. The 2 are taken as an atomic operation, so if a thread is returned, it's resumed by us, not any other threads or async events. This is useful if a consumer may be resumed by timeout, signals... besides its producer.

Parameters

susp_list	the list thread dequeued from. RT_NULL if no list.
thread_error	thread error number of the resuming thread. A negative value in this set will be discarded, and thread error will not be changed.

Returns

struct rt_thread * RT_NULL if failed, otherwise the thread resumed

rt_susp_list_resume_all()

rt_err_t rt_susp_list_resume_all	(	rt_list_t *	susp_list,
		rt_err_t	thread_error
	)

This function will resume all suspended threads in the IPC object list, including the suspended list of IPC object, and private list of mailbox etc.

Note

This function will resume all threads in the IPC object list. By contrast, the rt_ipc_list_resume() function will resume a suspended thread in the list of a IPC object.

Parameters

susp_list	is a pointer to a suspended thread list of the IPC object.
thread_error	thread error number of the resuming thread. A negative value in this set will be discarded, and thread error will not be changed.

Returns

Return the operation status. When the return value is RT_EOK, the function is successfully executed. When the return value is any other values, it means this operation failed.

rt_susp_list_resume_all_irq()

rt_err_t rt_susp_list_resume_all_irq	(	rt_list_t *	susp_list,
		rt_err_t	thread_error,
		struct rt_spinlock *	lock
	)

This function will resume all suspended threads in the IPC object list, including the suspended list of IPC object, and private list of mailbox etc. A lock is passing and hold while operating.

Note

This function will resume all threads in the IPC object list. By contrast, the rt_ipc_list_resume() function will resume a suspended thread in the list of a IPC object.

Parameters

susp_list	is a pointer to a suspended thread list of the IPC object.
thread_error	thread error number of the resuming thread. A negative value in this set will be discarded, and thread error will not be changed.
lock	the lock to be held while operating susp_list

Returns

Return the operation status. When the return value is RT_EOK, the function is successfully executed. When the return value is any other values, it means this operation failed.

rt_susp_list_enqueue()

rt_err_t rt_susp_list_enqueue	(	rt_list_t *	susp_list,
		rt_thread_t	thread,
		int	ipc_flags
	)

Add a thread to the suspend list.

Note

Caller must hold the scheduler lock

Parameters

susp_list	the list thread enqueued to
thread	the suspended thread
ipc_flags	the pattern of suspend list

Returns

RT_EOK on succeed, otherwise a failure

rt_susp_list_print()

void rt_susp_list_print

(

rt_list_t *

list

)

Print thread on suspend list to system console.

Suspend list - A basic building block for IPC primitives which interacts with scheduler directly. Its API is similar to a FIFO list.

Note: don't use in application codes directly

rt_thread_suspend_to_list()

rt_err_t rt_thread_suspend_to_list	(	rt_thread_t	thread,
		rt_list_t *	susp_list,
		int	ipc_flags,
		int	suspend_flag
	)

This function will suspend the specified thread and change it to suspend state.

Note

This function ONLY can suspend current thread itself. rt_thread_suspend(rt_thread_self());

Do not use the rt_thread_suspend to suspend other threads. You have no way of knowing what code a thread is executing when you suspend it. If you suspend a thread while sharing a resouce with other threads and occupying this resouce, starvation can occur very easily.

Parameters

thread	the thread to be suspended.
susp_list	the list thread enqueued to. RT_NULL if no list.
ipc_flags	is a flag for the thread object to be suspended. It determines how the thread is suspended. The flag can be ONE of the following values: RT_IPC_FLAG_PRIO The pending threads will queue in order of priority. RT_IPC_FLAG_FIFO The pending threads will queue in the first-in-first-out method (also known as first-come-first-served (FCFS) scheduling strategy). NOTE: RT_IPC_FLAG_FIFO is a non-real-time scheduling mode. It is strongly recommended to use RT_IPC_FLAG_PRIO to ensure the thread is real-time UNLESS your applications concern about the first-in-first-out principle, and you clearly understand that all threads involved in this semaphore will become non-real-time threads.
suspend_flag	status flag of the thread to be suspended.

Returns

Return the operation status. If the return value is RT_EOK, the function is successfully executed. If the return value is any other values, it means this operation failed.

enqueue thread on the push list before leaving critical region of scheduler, so we won't miss notification of async events.

rt_thread_defunct_enqueue()

void rt_thread_defunct_enqueue

(

rt_thread_t

thread

)

Enqueue a thread to defunct queue.

Parameters

thread

the thread to be enqueued.

Note

It must be called between rt_hw_interrupt_disable and rt_hw_interrupt_enable

rt_thread_defunct_dequeue()

rt_thread_t rt_thread_defunct_dequeue

(

void

)

Dequeue a thread from defunct queue.

rt_spin_lock_init()

void rt_spin_lock_init

(

struct rt_spinlock *

lock

)

Initialize a static spinlock object.

Parameters

lock	is a pointer to the spinlock to initialize.

rt_spin_lock()

void rt_spin_lock

(

struct rt_spinlock *

lock

)

This function will lock the spinlock, will lock the thread scheduler.

Note

If the spinlock is locked, the current CPU will keep polling the spinlock state until the spinlock is unlocked.

Parameters

lock	is a pointer to the spinlock.

rt_spin_unlock()

void rt_spin_unlock

(

struct rt_spinlock *

lock

)

This function will unlock the spinlock, will unlock the thread scheduler.

Parameters

lock	is a pointer to the spinlock.

rt_spin_lock_irqsave()

rt_base_t rt_spin_lock_irqsave

(

struct rt_spinlock *

lock

)

This function will disable the local interrupt and then lock the spinlock, will lock the thread scheduler.

Note

If the spinlock is locked, the current CPU will keep polling the spinlock state until the spinlock is unlocked.

Parameters

lock	is a pointer to the spinlock.

Returns

Return current cpu interrupt status.

rt_spin_unlock_irqrestore()

void rt_spin_unlock_irqrestore	(	struct rt_spinlock *	lock,
		rt_base_t	level
	)

This function will unlock the spinlock and then restore current cpu interrupt status, will unlock the thread scheduler.

Parameters

lock	is a pointer to the spinlock.
level	is interrupt status returned by rt_spin_lock_irqsave().