Semaphore

Collaboration diagram for Semaphore:

Data Structures
struct	rt_semaphore

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_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, int cmd, void *arg)

Detailed Description

Function Documentation

rt_sem_init()

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 static semaphore object.

Note

For the static semaphore 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_sem_create() function will allocate memory space automatically and initialize the semaphore.

See also

rt_sem_create()

Parameters

sem	is a pointer to the semaphore to initialize. It is assumed that storage for the semaphore will be allocated in your application.
name	is a pointer to the name you would like to give the semaphore.
value	is the initial value for the semaphore. If used to share resources, you should initialize the value as the number of available resources. If used to signal the occurrence of an event, you should initialize the value as 0.
flag	is the semaphore flag, which determines the queuing way of how multiple threads wait when the semaphore is not available. The semaphore 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.

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_sem_detach()

rt_err_t rt_sem_detach

(

rt_sem_t

sem

)

This function will detach a static semaphore object.

Note

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

See also

rt_sem_delete()

Parameters

sem	is a pointer to a semaphore 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 semaphore detach failed.

Warning

This function can ONLY detach a static semaphore initialized by the rt_sem_init() function. If the semaphore is created by the rt_sem_create() function, you MUST NOT USE this function to detach it, ONLY USE the rt_sem_delete() function to complete the deletion.

rt_sem_create()

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

Creating a semaphore object.

Note

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

See also

rt_sem_init()

Parameters

name	is a pointer to the name you would like to give the semaphore.
value	is the initial value for the semaphore. If used to share resources, you should initialize the value as the number of available resources. If used to signal the occurrence of an event, you should initialize the value as 0.
flag	is the semaphore flag, which determines the queuing way of how multiple threads wait when the semaphore is not available. The semaphore 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.

Returns

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

Warning

This function can NOT be called in interrupt context. You can use macor RT_DEBUG_NOT_IN_INTERRUPT to check it.

rt_sem_delete()

rt_err_t rt_sem_delete

(

rt_sem_t

sem

)

This function will delete a semaphore object and release the memory space.

Note

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

See also

rt_sem_detach()

Parameters

sem	is a pointer to a semaphore 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 semaphore detach failed.

Warning

This function can ONLY delete a semaphore initialized by the rt_sem_create() function. If the semaphore is initialized by the rt_sem_init() function, you MUST NOT USE this function to delete it, ONLY USE the rt_sem_detach() function to complete the detachment.

rt_sem_trytake()

rt_err_t rt_sem_trytake

(

rt_sem_t

sem

)

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

Note

This function is very similar to the rt_sem_take() function, when the semaphore is not available, the rt_sem_trytake() function will return immediately without waiting for a timeout. In other words, rt_sem_trytake(sem) has the same effect as rt_sem_take(sem, 0).

See also

rt_sem_take()

Parameters

sem	is a pointer to a semaphore 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 semaphore take failed.

rt_sem_release()

rt_err_t rt_sem_release

(

rt_sem_t

sem

)

This function will release a semaphore. If there is thread suspended on the semaphore, it will get resumed.

Note

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

Parameters

sem	is a pointer to a semaphore 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 semaphore release failed.

rt_sem_control()

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

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

Note

Currently this function only supports the RT_IPC_CMD_RESET command to reset the semaphore.

Parameters

sem	is a pointer to a semaphore object.
cmd	is a command word used to configure some attributions of the semaphore.
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.