Mutex

Collaboration diagram for Mutex:

Data Structures
struct	rt_mutex

Functions
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)
void	rt_mutex_drop_thread (rt_mutex_t mutex, rt_thread_t thread)
rt_uint8_t	rt_mutex_setprioceiling (rt_mutex_t mutex, rt_uint8_t priority)
rt_uint8_t	rt_mutex_getprioceiling (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_trytake (rt_mutex_t mutex)
rt_err_t	rt_mutex_release (rt_mutex_t mutex)
rt_err_t	rt_mutex_control (rt_mutex_t mutex, int cmd, void *arg)

Detailed Description

Function Documentation

rt_mutex_init()

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

Initialize a static mutex object.

Note

For the static mutex object, its memory space is allocated by the compiler during compiling, and shall placed on the read-write data segment or on the uninitialized data segment. By contrast, the rt_mutex_create() function will automatically allocate memory space and initialize the mutex.

See also

rt_mutex_create()

Parameters

mutex	is a pointer to the mutex to initialize. It is assumed that storage for the mutex will be allocated in your application.
name	is a pointer to the name that given to the mutex.
flag	is the mutex flag, which determines the queuing way of how multiple threads wait when the mutex is not available. NOTE: This parameter has been obsoleted. It can be RT_IPC_FLAG_PRIO, RT_IPC_FLAG_FIFO or RT_NULL.

Returns

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

Warning

This function can ONLY be called from threads.

rt_mutex_detach()

rt_err_t rt_mutex_detach

(

rt_mutex_t

mutex

)

This function will detach a static mutex object.

Note

This function is used to detach a static mutex object which is initialized by rt_mutex_init() function. By contrast, the rt_mutex_delete() function will delete a mutex object. When the mutex is successfully detached, it will resume all suspended threads in the mutex list.

See also

rt_mutex_delete()

Parameters

mutex

is a pointer to a mutex object to be detached.

Returns

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

Warning

This function can ONLY detach a static mutex initialized by the rt_mutex_init() function. If the mutex is created by the rt_mutex_create() function, you MUST NOT USE this function to detach it, ONLY USE the rt_mutex_delete() function to complete the deletion.

rt_mutex_drop_thread()

void rt_mutex_drop_thread	(	rt_mutex_t	mutex,
		rt_thread_t	thread
	)

drop a thread from the suspend list of mutex

Parameters

mutex	is a pointer to a mutex object.
thread	is the thread should be dropped from mutex.

Should change the priority of mutex owner thread Note: After current thread is detached from mutex pending list, there is a chance that the mutex owner has been released the mutex. Which means mutex->owner can be NULL at this point. If that happened, it had already reset its priority. So it's okay to skip

rt_mutex_setprioceiling()

rt_uint8_t rt_mutex_setprioceiling	(	rt_mutex_t	mutex,
		rt_uint8_t	priority
	)

set the prioceiling attribute of the mutex.

Parameters

mutex	is a pointer to a mutex object.
priority	is the priority should be set to mutex.

Returns

return the old priority ceiling

rt_mutex_getprioceiling()

rt_uint8_t rt_mutex_getprioceiling

(

rt_mutex_t

mutex

)

set the prioceiling attribute of the mutex.

Parameters

mutex

is a pointer to a mutex object.

Returns

return the current priority ceiling of the mutex.

rt_mutex_create()

rt_mutex_t rt_mutex_create	(	const char *	name,
		rt_uint8_t	flag
	)

This function will create a mutex object.

Note

For the mutex object, its memory space is automatically allocated. By contrast, the rt_mutex_init() function will initialize a static mutex object.

See also

rt_mutex_init()

Parameters

name	is a pointer to the name that given to the mutex.
flag	is the mutex flag, which determines the queuing way of how multiple threads wait when the mutex is not available. NOTE: This parameter has been obsoleted. It can be RT_IPC_FLAG_PRIO, RT_IPC_FLAG_FIFO or RT_NULL.

Returns

Return a pointer to the mutex object. When the return value is RT_NULL, it means the creation failed.

Warning

This function can ONLY be called from threads.

rt_mutex_delete()

rt_err_t rt_mutex_delete

(

rt_mutex_t

mutex

)

This function will delete a mutex object and release this memory space.

Note

This function is used to delete a mutex object which is created by the rt_mutex_create() function. By contrast, the rt_mutex_detach() function will detach a static mutex object. When the mutex is successfully deleted, it will resume all suspended threads in the mutex list.

See also

rt_mutex_detach()

Parameters

mutex

is a pointer to a mutex object to be deleted.

Returns

Return the operation status. When the return value is RT_EOK, the operation is successful. If the return value is any other values, it means that the mutex detach failed.

Warning

This function can ONLY delete a mutex initialized by the rt_mutex_create() function. If the mutex is initialized by the rt_mutex_init() function, you MUST NOT USE this function to delete it, ONLY USE the rt_mutex_detach() function to complete the detachment.

rt_mutex_trytake()

rt_err_t rt_mutex_trytake

(

rt_mutex_t

mutex

)

This function will try to take a mutex, if the mutex is unavailable, the thread returns immediately.

Note

This function is very similar to the rt_mutex_take() function, when the mutex is not available, except that rt_mutex_trytake() will return immediately without waiting for a timeout when the mutex is not available. In other words, rt_mutex_trytake(mutex) has the same effect as rt_mutex_take(mutex, 0).

See also

rt_mutex_take()

Parameters

mutex

is a pointer to a mutex object.

Returns

Return the operation status. ONLY When the return value is RT_EOK, the operation is successful. If the return value is any other values, it means that the mutex take failed.

rt_mutex_release()

rt_err_t rt_mutex_release

(

rt_mutex_t

mutex

)

This function will release a mutex. If there is thread suspended on the mutex, the thread will be resumed.

Note

If there are threads suspended on this mutex, the first thread in the list of this mutex object will be resumed, and a thread scheduling (rt_schedule) will be executed. If no threads are suspended on this mutex, the count value mutex->value of this mutex will increase by 1.

Parameters

mutex

is a pointer to a mutex object.

Returns

Return the operation status. When the return value is RT_EOK, the operation is successful. If the return value is any other values, it means that the mutex release failed.

a timeout timer had triggered while we try. So we skip this thread and try again.

rt_mutex_control()

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

This function will set some extra attributions of a mutex object.

Note

Currently this function does not implement the control function.

Parameters

mutex	is a pointer to a mutex object.
cmd	is a command word used to configure some attributions of the mutex.
arg	is the argument of the function to execute the command.

Returns

Return the operation status. When the return value is RT_EOK, the operation is successful. If the return value is any other values, it means that this function failed to execute.