Inter-Thread Communication
[RT-Thread Kernel API]


Functions
rt_err_t	rt_sem_init (rt_sem_t sem, const char *name, rt_uint32_t value, rt_uint8_t flag)
rt_err_t	rt_sem_detach (rt_sem_t sem)
rt_sem_t	rt_sem_create (const char *name, rt_uint32_t value, rt_uint8_t flag)
rt_err_t	rt_sem_delete (rt_sem_t sem)
rt_err_t	rt_sem_take (rt_sem_t sem, rt_int32_t time)
rt_err_t	rt_sem_trytake (rt_sem_t sem)
rt_err_t	rt_sem_release (rt_sem_t sem)
rt_err_t	rt_sem_control (rt_sem_t sem, rt_uint8_t cmd, void *arg)
rt_err_t	rt_mutex_init (rt_mutex_t mutex, const char *name, rt_uint8_t flag)
rt_err_t	rt_mutex_detach (rt_mutex_t mutex)
rt_mutex_t	rt_mutex_create (const char *name, rt_uint8_t flag)
rt_err_t	rt_mutex_delete (rt_mutex_t mutex)
rt_err_t	rt_mutex_take (rt_mutex_t mutex, rt_int32_t time)
rt_err_t	rt_mutex_release (rt_mutex_t mutex)
rt_err_t	rt_mutex_control (rt_mutex_t mutex, rt_uint8_t cmd, void *arg)
rt_err_t	rt_fast_event_init (rt_fast_event_t event, const char *name, rt_uint8_t flag)
rt_err_t	rt_fast_event_detach (rt_fast_event_t event)
rt_fast_event_t	rt_fast_event_create (const char *name, rt_uint8_t flag)
rt_err_t	rt_fast_event_delete (rt_fast_event_t event)
rt_err_t	rt_fast_event_send (rt_fast_event_t event, rt_uint8_t bit)
rt_err_t	rt_fast_event_recv (rt_fast_event_t event, rt_uint8_t bit, rt_uint8_t opt, rt_int32_t timeout)
rt_err_t	rt_fast_event_control (rt_fast_event_t event, rt_uint8_t cmd, void *arg)
rt_err_t	rt_event_init (rt_event_t event, const char *name, rt_uint8_t flag)
rt_err_t	rt_event_detach (rt_event_t event)
rt_event_t	rt_event_create (const char *name, rt_uint8_t flag)
rt_err_t	rt_event_delete (rt_event_t event)
rt_err_t	rt_event_send (rt_event_t event, rt_uint32_t set)
rt_err_t	rt_event_recv (rt_event_t event, rt_uint32_t set, rt_uint8_t opt, rt_int32_t timeout, rt_uint32_t *recved)
rt_err_t	rt_event_control (rt_event_t event, rt_uint8_t cmd, void *arg)
rt_err_t	rt_mb_init (rt_mailbox_t mb, const char name, void msgpool, rt_size_t size, rt_uint8_t flag)
rt_err_t	rt_mb_detach (rt_mailbox_t mb)
rt_mailbox_t	rt_mb_create (const char *name, rt_size_t size, rt_uint8_t flag)
rt_err_t	rt_mb_delete (rt_mailbox_t mb)
rt_err_t	rt_mb_send (rt_mailbox_t mb, rt_uint32_t value)
rt_err_t	rt_mb_recv (rt_mailbox_t mb, rt_uint32_t *value, rt_int32_t timeout)
rt_err_t	rt_mb_control (rt_mailbox_t mb, rt_uint8_t cmd, void *arg)
rt_err_t	rt_mq_init (rt_mq_t mq, const char name, void msgpool, rt_size_t msg_size, rt_size_t pool_size, rt_uint8_t flag)
rt_err_t	rt_mq_detach (rt_mq_t mq)
rt_mq_t	rt_mq_create (const char *name, rt_size_t msg_size, rt_size_t max_msgs, rt_uint8_t flag)
rt_err_t	rt_mq_delete (rt_mq_t mq)
rt_err_t	rt_mq_send (rt_mq_t mq, void *buffer, rt_size_t size)
rt_err_t	rt_mq_urgent (rt_mq_t mq, void *buffer, rt_size_t size)
rt_err_t	rt_mq_recv (rt_mq_t mq, void *buffer, rt_size_t size, rt_int32_t timeout)
rt_err_t	rt_mq_control (rt_mq_t mq, rt_uint8_t cmd, void *arg)
rt_inline rt_err_t	rt_ipc_object_init (struct rt_ipc_object *ipc)
rt_inline rt_err_t	rt_ipc_object_suspend (struct rt_ipc_object ipc, struct rt_thread thread)
rt_inline rt_err_t	rt_ipc_object_resume (struct rt_ipc_object *ipc)
rt_inline rt_err_t	rt_ipc_object_resume_all (struct rt_ipc_object *ipc)

Detailed Description

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 thead 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.

Function Documentation

rt_err_t rt_event_control	(	rt_event_t	event,
		rt_uint8_t	cmd,
		void *	arg
	)

This function can get or set some extra attributions of an event object.

Parameters:

	event	the event object
	cmd	the execution command
	arg	the execution argument

Returns:: the error code

rt_event_t rt_event_create	(	const char *	name,
		rt_uint8_t	flag
	)

This function will create an event object from system resource

Parameters:

	name	the name of event
	flag	the flag of event

Returns:: the created event, RT_NULL on error happen

rt_err_t rt_event_delete ( rt_event_t event )

This function will delete an event object and release the memory

Parameters:

event

the event object

Returns:: the error code

rt_err_t rt_event_detach ( rt_event_t event )

This function will detach an event object from resource management

Parameters:

event

the event object

Returns:: the operation status, RT_EOK on successful

rt_err_t rt_event_init	(	rt_event_t	event,
		const char *	name,
		rt_uint8_t	flag
	)

This function will initialize an event and put it under control of resource management.

Parameters:

	event	the event object
	name	the name of event
	flag	the flag of event

Returns:: the operation status, RT_EOK on successful

rt_err_t rt_event_recv	(	rt_event_t	event,
		rt_uint32_t	set,
		rt_uint8_t	option,
		rt_int32_t	timeout,
		rt_uint32_t *	recved
	)

This function will receive an event from event object, if the event is unavailable, the thread shall wait for a specified time.

Parameters:

	event	the fast event object
	set	the interested event set
	option	the receive option
	timeout	the waiting time
	recved	the received event

Returns:: the error code

rt_err_t rt_event_send	(	rt_event_t	event,
		rt_uint32_t	set
	)

This function will send an event to the event object, if there are threads suspended on event object, it will be waked up.

Parameters:

	event	the event object
	set	the event set

Returns:: the error code

rt_err_t rt_fast_event_control	(	rt_fast_event_t	event,
		rt_uint8_t	cmd,
		void *	arg
	)

This function can get or set some extra attributions of a fast event object.

Parameters:

	event	the event object
	cmd	the execution command
	arg	the execution argument

Returns:: the error code

rt_fast_event_t rt_fast_event_create	(	const char *	name,
		rt_uint8_t	flag
	)

This function will create a fast event object from system resource

Parameters:

	name	the name of fast event
	flag	the flag of fast event

Returns:: the created fast event, RT_NULL on error happen

rt_err_t rt_fast_event_delete ( rt_fast_event_t event )

This function will delete a fast event object and release the memory

Parameters:

event

the fast event object

Returns:: the error code

rt_err_t rt_fast_event_detach ( rt_fast_event_t event )

This function will detach a fast event from resource management

Parameters:

event

the fast event object

Returns:: the operation status, RT_EOK on successful

rt_err_t rt_fast_event_init	(	rt_fast_event_t	event,
		const char *	name,
		rt_uint8_t	flag
	)

This function will initialize a fast event and put it under control of resource management.

Parameters:

	event	the fast event object
	name	the name of fast event
	flag	the flag of fast event

Returns:: the operation status, RT_EOK on successful

rt_err_t rt_fast_event_recv	(	rt_fast_event_t	event,
		rt_uint8_t	bit,
		rt_uint8_t	option,
		rt_int32_t	timeout
	)

This function will receive an event from fast event object, if the event is unavailable, the thread shall wait for a specified time.

Parameters:

	event	the fast event object
	bit	the interested event
	option	the receive option
	timeout	the waiting time

Returns:: the error code

rt_err_t rt_fast_event_send	(	rt_fast_event_t	event,
		rt_uint8_t	bit
	)

This function will send an event to the fast event object, if there are threads suspended on fast event object, it will be waked up.

Parameters:

	event	the fast event object
	bit	the event bit

Returns:: the error code

rt_inline rt_err_t rt_ipc_object_init ( struct rt_ipc_object * ipc )

This function will initialize an IPC object

Parameters:

ipc

the IPC object

Returns:: the operation status, RT_EOK on successful

rt_inline rt_err_t rt_ipc_object_resume ( struct rt_ipc_object * ipc )

This function will resume a thread from an IPC object:

remove the thread from suspend queue of IPC object
put the thread into system ready queue

Parameters:

ipc

the IPC object

Returns:: the operation status, RT_EOK on successful

rt_inline rt_err_t rt_ipc_object_resume_all ( struct rt_ipc_object * ipc )

This function will resume all suspended threads in an IPC object.

Parameters:

ipc

the IPC object

Returns:: the operation status, RT_EOK on successful

rt_inline rt_err_t rt_ipc_object_suspend	(	struct rt_ipc_object *	ipc,
		struct rt_thread *	thread
	)

This function will suspend a thread for a specified IPC object and put the thread into suspend queue of IPC object

Parameters:

	ipc	the IPC object
	thread	the thread object to be suspended

Returns:: the operation status, RT_EOK on successful

rt_err_t rt_mb_control	(	rt_mailbox_t	mb,
		rt_uint8_t	cmd,
		void *	arg
	)

This function can get or set some extra attributions of a mailbox object.

Parameters:

	mb	the mailbox object
	cmd	the execution command
	arg	the execution argument

Returns:: the error code

rt_mailbox_t rt_mb_create	(	const char *	name,
		rt_size_t	size,
		rt_uint8_t	flag
	)

This function will create a mailbox object from system resource

Parameters:

	name	the name of mailbox
	size	the size of mailbox
	flag	the flag of mailbox

Returns:: the created mailbox, RT_NULL on error happen

rt_err_t rt_mb_delete ( rt_mailbox_t mb )

This function will delete a mailbox object and release the memory

Parameters:

mb

the mailbox object

Returns:: the error code

rt_err_t rt_mb_detach ( rt_mailbox_t mb )

This function will detach a mailbox from resource management

Parameters:

mb

the mailbox object

Returns:: the operation status, RT_EOK on successful

rt_err_t rt_mb_init	(	rt_mailbox_t	mb,
		const char *	name,
		void *	msgpool,
		rt_size_t	size,
		rt_uint8_t	flag
	)

This function will initialize a mailbox and put it under control of resource management.

Parameters:

	mb	the mailbox object
	name	the name of mailbox
	msgpool	the begin address of buffer to save received mail
	size	the size of mailbox
	flag	the flag of mailbox

Returns:: the operation status, RT_EOK on successful

rt_err_t rt_mb_recv	(	rt_mailbox_t	mb,
		rt_uint32_t *	value,
		rt_int32_t	timeout
	)

This function will receive a mail from mailbox object, if there is no mail in mailbox object, the thread shall wait for a specified time.

Parameters:

	mb	the mailbox object
	value	the received mail will be saved in
	timeout	the waiting time

Returns:: the error code

rt_err_t rt_mb_send	(	rt_mailbox_t	mb,
		rt_uint32_t	value
	)

This function will send a mail to mailbox object, if there are threads suspended on mailbox object, it will be waked up.

Parameters:

	mb	the mailbox object
	value	the mail

Returns:: the error code

rt_err_t rt_mq_control	(	rt_mq_t	mq,
		rt_uint8_t	cmd,
		void *	arg
	)

This function can get or set some extra attributions of a message queue object.

Parameters:

	mq	the message queue object
	cmd	the execution command
	arg	the execution argument

Returns:: the error code

rt_mq_t rt_mq_create	(	const char *	name,
		rt_size_t	msg_size,
		rt_size_t	max_msgs,
		rt_uint8_t	flag
	)

This function will create a message queue object from system resource

Parameters:

	name	the name of message queue
	msg_size	the size of message
	max_msgs	the maximum number of message in queue
	flag	the flag of message queue

Returns:: the created message queue, RT_NULL on error happen

rt_err_t rt_mq_delete ( rt_mq_t mq )

This function will delete a message queue object and release the memory

Parameters:

mq

the message queue object

Returns:: the error code

rt_err_t rt_mq_detach ( rt_mq_t mq )

This function will detach a message queue object from resource management

Parameters:

mq

the message queue object

Returns:: the operation status, RT_EOK on successful

rt_err_t rt_mq_init	(	rt_mq_t	mq,
		const char *	name,
		void *	msgpool,
		rt_size_t	msg_size,
		rt_size_t	pool_size,
		rt_uint8_t	flag
	)

This function will initialize a message queue and put it under control of resource management.

Parameters:

	mq	the message object
	name	the name of message queue
	msgpool	the beginning address of buffer to save messages
	msg_size	the maximum size of message
	pool_size	the size of buffer to save messages
	flag	the flag of message queue

Returns:: the operation status, RT_EOK on successful

rt_err_t rt_mq_recv	(	rt_mq_t	mq,
		void *	buffer,
		rt_size_t	size,
		rt_int32_t	timeout
	)

This function will receive a message from message queue object, if there is no message in message queue object, the thread shall wait for a specified time.

Parameters:

	mq	the message queue object
	buffer	the received message will be saved in
	size	the size of buffer
	timeout	the waiting time

Returns:: the error code

rt_err_t rt_mq_send	(	rt_mq_t	mq,
		void *	buffer,
		rt_size_t	size
	)

This function will send a message to message queue object, if there are threads suspended on message queue object, it will be waked up.

Parameters:

	mq	the message queue object
	buffer	the message
	size	the size of buffer

Returns:: the error code

rt_err_t rt_mq_urgent	(	rt_mq_t	mq,
		void *	buffer,
		rt_size_t	size
	)

This function will send urgently a message to message queue object, which means the message will be inserted to the head of message queue. If there are threads suspended on message queue object, it will be waked up.

Parameters:

	mq	the message queue object
	buffer	the message
	size	the size of buffer

Returns:: the error code

rt_err_t rt_mutex_control	(	rt_mutex_t	mutex,
		rt_uint8_t	cmd,
		void *	arg
	)

This function can get or set some extra attributions of a mutex object.

Parameters:

	mutex	the mutex object
	cmd	the execution command
	arg	the execution argument

Returns:: the error code

rt_mutex_t rt_mutex_create	(	const char *	name,
		rt_uint8_t	flag
	)

This function will create a mutex from system resource

Parameters:

	name	the name of mutex
	flag	the flag of mutex

Returns:: the created mutex, RT_NULL on error happen

See also:: rt_mutex_init

rt_err_t rt_mutex_delete ( rt_mutex_t mutex )

This function will delete a mutex object and release the memory

Parameters:

mutex

the mutex object

Returns:: the error code

See also:: rt_mutex_detach

rt_err_t rt_mutex_detach ( rt_mutex_t mutex )

This function will detach a mutex from resource management

Parameters:

mutex

the mutex object

Returns:: the operation status, RT_EOK on successful

See also:: rt_mutex_delete

rt_err_t rt_mutex_init	(	rt_mutex_t	mutex,
		const char *	name,
		rt_uint8_t	flag
	)

This function will initialize a mutex and put it under control of resource management.

Parameters:

	mutex	the mutex object
	name	the name of mutex
	flag	the flag of mutex

Returns:: the operation status, RT_EOK on successful

rt_err_t rt_mutex_release ( rt_mutex_t mutex )

This function will release a mutex, if there are threads suspended on mutex, it will be waked up.

Parameters:

mutex

the mutex object

Returns:: the error code

rt_err_t rt_mutex_take	(	rt_mutex_t	mutex,
		rt_int32_t	time
	)

This function will take a mutex, if the mutex is unavailable, the thread shall wait for a specified time.

Parameters:

	mutex	the mutex object
	time	the waiting time

Returns:: the error code

rt_err_t rt_sem_control	(	rt_sem_t	sem,
		rt_uint8_t	cmd,
		void *	arg
	)

This function can get or set some extra attributions of a semaphore object.

Parameters:

	sem	the semaphore object
	cmd	the execution command
	arg	the execution argument

Returns:: the error code

rt_sem_t rt_sem_create	(	const char *	name,
		rt_uint32_t	value,
		rt_uint8_t	flag
	)

This function will create a semaphore from system resource

Parameters:

	name	the name of semaphore
	value	the init value of semaphore
	flag	the flag of semaphore

Returns:: the created semaphore, RT_NULL on error happen

See also:: rt_sem_init

rt_err_t rt_sem_delete ( rt_sem_t sem )

This function will delete a semaphore object and release the memory

Parameters:

sem

the semaphore object

Returns:: the error code

See also:: rt_sem_detach

rt_err_t rt_sem_detach ( rt_sem_t sem )

This function will detach a semaphore from resource management

Parameters:

sem

the semaphore object

Returns:: the operation status, RT_EOK on successful

See also:: rt_sem_delete

rt_err_t rt_sem_init	(	rt_sem_t	sem,
		const char *	name,
		rt_uint32_t	value,
		rt_uint8_t	flag
	)

This function will initialize a semaphore and put it under control of resource management.

Parameters:

	sem	the semaphore object
	name	the name of semaphore
	value	the init value of semaphore
	flag	the flag of semaphore

Returns:: the operation status, RT_EOK on successful

rt_err_t rt_sem_release ( rt_sem_t sem )

This function will release a semaphore, if there are threads suspended on semaphore, it will be waked up.

Parameters:

sem

the semaphore object

Returns:: the error code

rt_err_t rt_sem_take	(	rt_sem_t	sem,
		rt_int32_t	time
	)

This function will take a semaphore, if the semaphore is unavailable, the thread shall wait for a specified time.

Parameters:

	sem	the semaphore object
	time	the waiting time

Returns:: the error code

rt_err_t rt_sem_trytake ( rt_sem_t sem )

This function will try to take a semaphore and immediately return

Parameters:

sem

the semaphore object

Returns:: the error code

Inter-Thread Communication [RT-Thread Kernel API]

Functions

Detailed Description

Function Documentation

Inter-Thread Communication
[RT-Thread Kernel API]