Semaphore

Semaphore 的协作图:

结构体
struct	rt_semaphore

类型定义
typedef struct rt_semaphore *	rt_sem_t

函数
rt_err_t	rt_sem_init (rt_sem_t sem, const char *name, rt_uint32_t value, rt_uint8_t flag)
	RTM_EXPORT (rt_sem_init)
rt_err_t	rt_sem_detach (rt_sem_t sem)
	RTM_EXPORT (rt_sem_detach)
rt_sem_t	rt_sem_create (const char *name, rt_uint32_t value, rt_uint8_t flag)
	RTM_EXPORT (rt_sem_create)
rt_err_t	rt_sem_delete (rt_sem_t sem)
	RTM_EXPORT (rt_sem_delete)
rt_err_t	rt_sem_take (rt_sem_t sem, rt_int32_t time)
	RTM_EXPORT (rt_sem_take)
rt_err_t	rt_sem_take_interruptible (rt_sem_t sem, rt_int32_t time)
	RTM_EXPORT (rt_sem_take_interruptible)
rt_err_t	rt_sem_take_killable (rt_sem_t sem, rt_int32_t time)
	RTM_EXPORT (rt_sem_take_killable)
rt_err_t	rt_sem_trytake (rt_sem_t sem)
	RTM_EXPORT (rt_sem_trytake)
rt_err_t	rt_sem_release (rt_sem_t sem)
	RTM_EXPORT (rt_sem_release)
rt_err_t	rt_sem_control (rt_sem_t sem, int cmd, void *arg)
	RTM_EXPORT (rt_sem_control)

详细描述

类型定义说明

rt_sem_t

typedef struct rt_semaphore* rt_sem_t

在文件 rtdef.h 第 1010 行定义.

函数说明

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.

注解

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.

参见

rt_sem_create()

参数

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.

返回

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.

警告

This function can ONLY be called from threads.

在文件 ipc.c 第 376 行定义.

{
    RT_ASSERT(sem != RT_NULL);
    RT_ASSERT(value < 0x10000U);
    RT_ASSERT((flag == RT_IPC_FLAG_FIFO) || (flag == RT_IPC_FLAG_PRIO));
 
    /* initialize object */
    rt_object_init(&(sem->parent.parent), RT_Object_Class_Semaphore, name);
 
    _sem_object_init(sem, value, flag, RT_SEM_VALUE_MAX);
 
    return RT_EOK;
}

引用了 rt_ipc_object::parent, rt_semaphore::parent, RT_ASSERT, RT_IPC_FLAG_FIFO, RT_IPC_FLAG_PRIO, RT_NULL, RT_Object_Class_Semaphore, rt_object_init() , 以及 RT_SEM_VALUE_MAX.

函数调用图:

这是这个函数的调用关系图:

RTM_EXPORT() [1/10]

RTM_EXPORT

(

rt_sem_init

)

引用了 rt_sem_init().

函数调用图:

rt_sem_detach()

rt_err_t rt_sem_detach

(

rt_sem_t

sem

)

This function will detach a static semaphore object.

注解

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.

参见

rt_sem_delete()

参数

sem	is a pointer to a semaphore object to be detached.

返回

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.

警告

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.

在文件 ipc.c 第 413 行定义.

{
    rt_base_t level;
 
    /* parameter check */
    RT_ASSERT(sem != RT_NULL);
    RT_ASSERT(rt_object_get_type(&sem->parent.parent) == RT_Object_Class_Semaphore);
    RT_ASSERT(rt_object_is_systemobject(&sem->parent.parent));
 
    level = rt_spin_lock_irqsave(&(sem->spinlock));
    /* wakeup all suspended threads */
    rt_susp_list_resume_all(&(sem->parent.suspend_thread), RT_ERROR);
    rt_spin_unlock_irqrestore(&(sem->spinlock), level);
 
    /* detach semaphore object */
    rt_object_detach(&(sem->parent.parent));
 
    return RT_EOK;
}

引用了 rt_ipc_object::parent, rt_semaphore::parent, RT_ASSERT, RT_NULL, RT_Object_Class_Semaphore, rt_object_detach(), rt_object_get_type(), rt_object_is_systemobject(), rt_spin_lock_irqsave(), rt_spin_unlock_irqrestore(), rt_susp_list_resume_all(), rt_semaphore::spinlock , 以及 rt_ipc_object::suspend_thread.

函数调用图:

这是这个函数的调用关系图:

RTM_EXPORT() [2/10]

RTM_EXPORT

(

rt_sem_detach

)

引用了 rt_sem_detach().

函数调用图:

rt_sem_create()

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

Creating a semaphore object.

注解

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

参见

rt_sem_init()

参数

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.

返回

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

警告

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

在文件 ipc.c 第 467 行定义.

{
    rt_sem_t sem;
 
    RT_ASSERT(value < 0x10000U);
    RT_ASSERT((flag == RT_IPC_FLAG_FIFO) || (flag == RT_IPC_FLAG_PRIO));
 
    RT_DEBUG_NOT_IN_INTERRUPT;
 
    /* allocate object */
    sem = (rt_sem_t)rt_object_allocate(RT_Object_Class_Semaphore, name);
    if (sem == RT_NULL)
        return sem;
 
    _sem_object_init(sem, value, flag, RT_SEM_VALUE_MAX);
 
    return sem;
}

引用了 RT_ASSERT, RT_DEBUG_NOT_IN_INTERRUPT, RT_IPC_FLAG_FIFO, RT_IPC_FLAG_PRIO, RT_NULL, rt_object_allocate(), RT_Object_Class_Semaphore , 以及 RT_SEM_VALUE_MAX.

函数调用图:

这是这个函数的调用关系图:

RTM_EXPORT() [3/10]

RTM_EXPORT

(

rt_sem_create

)

引用了 rt_sem_create().

函数调用图:

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.

注解

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.

参见

rt_sem_detach()

参数

sem	is a pointer to a semaphore object to be deleted.

返回

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.

警告

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.

在文件 ipc.c 第 506 行定义.

{
    rt_ubase_t level;
 
    /* parameter check */
    RT_ASSERT(sem != RT_NULL);
    RT_ASSERT(rt_object_get_type(&sem->parent.parent) == RT_Object_Class_Semaphore);
    RT_ASSERT(rt_object_is_systemobject(&sem->parent.parent) == RT_FALSE);
 
    RT_DEBUG_NOT_IN_INTERRUPT;
 
    level = rt_spin_lock_irqsave(&(sem->spinlock));
    /* wakeup all suspended threads */
    rt_susp_list_resume_all(&(sem->parent.suspend_thread), RT_ERROR);
    rt_spin_unlock_irqrestore(&(sem->spinlock), level);
 
    /* delete semaphore object */
    rt_object_delete(&(sem->parent.parent));
 
    return RT_EOK;
}

引用了 rt_ipc_object::parent, rt_semaphore::parent, RT_ASSERT, RT_DEBUG_NOT_IN_INTERRUPT, RT_FALSE, RT_NULL, RT_Object_Class_Semaphore, rt_object_delete(), rt_object_get_type(), rt_object_is_systemobject(), rt_spin_lock_irqsave(), rt_spin_unlock_irqrestore(), rt_susp_list_resume_all(), rt_semaphore::spinlock , 以及 rt_ipc_object::suspend_thread.

函数调用图:

这是这个函数的调用关系图:

RTM_EXPORT() [4/10]

RTM_EXPORT

(

rt_sem_delete

)

引用了 RT_NULL, RT_Object_Class_Semaphore , 以及 rt_sem_delete().

函数调用图:

rt_sem_take()

rt_err_t rt_sem_take	(	rt_sem_t	sem,
		rt_int32_t	time )

在文件 ipc.c 第 644 行定义.

{
    return _rt_sem_take(sem, time, RT_UNINTERRUPTIBLE);
}

引用了 RT_UNINTERRUPTIBLE.

这是这个函数的调用关系图:

RTM_EXPORT() [5/10]

RTM_EXPORT

(

rt_sem_take

)

引用了 rt_sem_take().

函数调用图:

rt_sem_take_interruptible()

rt_err_t rt_sem_take_interruptible	(	rt_sem_t	sem,
		rt_int32_t	time )

在文件 ipc.c 第 650 行定义.

{
    return _rt_sem_take(sem, time, RT_INTERRUPTIBLE);
}

引用了 RT_INTERRUPTIBLE.

这是这个函数的调用关系图:

RTM_EXPORT() [6/10]

RTM_EXPORT

(

rt_sem_take_interruptible

)

引用了 rt_sem_take_interruptible().

函数调用图:

rt_sem_take_killable()

rt_err_t rt_sem_take_killable	(	rt_sem_t	sem,
		rt_int32_t	time )

在文件 ipc.c 第 656 行定义.

{
    return _rt_sem_take(sem, time, RT_KILLABLE);
}

引用了 RT_KILLABLE.

这是这个函数的调用关系图:

RTM_EXPORT() [7/10]

RTM_EXPORT

(

rt_sem_take_killable

)

引用了 rt_sem_take_killable().

函数调用图:

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.

注解

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

参见

rt_sem_take()

参数

sem	is a pointer to a semaphore object.

返回

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.

在文件 ipc.c 第 676 行定义.

{
    return rt_sem_take(sem, RT_WAITING_NO);
}

引用了 rt_sem_take() , 以及 RT_WAITING_NO.

函数调用图:

这是这个函数的调用关系图:

RTM_EXPORT() [8/10]

RTM_EXPORT

(

rt_sem_trytake

)

引用了 rt_sem_trytake().

函数调用图:

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.

注解

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.

参数

sem	is a pointer to a semaphore object.

返回

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.

在文件 ipc.c 第 695 行定义.

{
    rt_base_t level;
    rt_bool_t need_schedule;
 
    /* parameter check */
    RT_ASSERT(sem != RT_NULL);
    RT_ASSERT(rt_object_get_type(&sem->parent.parent) == RT_Object_Class_Semaphore);
 
    RT_OBJECT_HOOK_CALL(rt_object_put_hook, (&(sem->parent.parent)));
 
    need_schedule = RT_FALSE;
 
    level = rt_spin_lock_irqsave(&(sem->spinlock));
 
    LOG_D("thread %s releases sem:%s, which value is: %d",
          rt_thread_self()->parent.name,
          sem->parent.parent.name,
          sem->value);
 
    if (!rt_list_isempty(&sem->parent.suspend_thread))
    {
        /* resume the suspended thread */
        rt_susp_list_dequeue(&(sem->parent.suspend_thread), RT_EOK);
        need_schedule = RT_TRUE;
    }
    else
    {
        if(sem->value < sem->max_value)
        {
            sem->value ++; /* increase value */
        }
        else
        {
            rt_spin_unlock_irqrestore(&(sem->spinlock), level);
            return -RT_EFULL; /* value overflowed */
        }
    }
 
    rt_spin_unlock_irqrestore(&(sem->spinlock), level);
 
    /* resume a thread, re-schedule */
    if (need_schedule == RT_TRUE)
        rt_schedule();
 
    return RT_EOK;
}

引用了 LOG_D, rt_semaphore::max_value, rt_object::name, rt_ipc_object::parent, rt_semaphore::parent, rt_thread::parent, RT_ASSERT, RT_FALSE, rt_list_isempty(), RT_NULL, RT_Object_Class_Semaphore, rt_object_get_type(), RT_OBJECT_HOOK_CALL, rt_schedule(), rt_spin_lock_irqsave(), rt_spin_unlock_irqrestore(), rt_susp_list_dequeue(), rt_thread_self(), RT_TRUE, rt_semaphore::spinlock, rt_ipc_object::suspend_thread , 以及 rt_semaphore::value.

函数调用图:

这是这个函数的调用关系图:

RTM_EXPORT() [9/10]

RTM_EXPORT

(

rt_sem_release

)

引用了 rt_sem_release().

函数调用图:

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.

注解

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

参数

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.

返回

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.

在文件 ipc.c 第 759 行定义.

{
    rt_base_t level;
 
    /* parameter check */
    RT_ASSERT(sem != RT_NULL);
    RT_ASSERT(rt_object_get_type(&sem->parent.parent) == RT_Object_Class_Semaphore);
 
    if (cmd == RT_IPC_CMD_RESET)
    {
        rt_ubase_t value;
 
        /* get value */
        value = (rt_uintptr_t)arg;
        level = rt_spin_lock_irqsave(&(sem->spinlock));
 
        /* resume all waiting thread */
        rt_susp_list_resume_all(&sem->parent.suspend_thread, RT_ERROR);
 
        /* set new value */
        sem->value = (rt_uint16_t)value;
        rt_spin_unlock_irqrestore(&(sem->spinlock), level);
        rt_schedule();
 
        return RT_EOK;
    }
    else if (cmd == RT_IPC_CMD_SET_VLIMIT)
    {
        rt_ubase_t max_value;
        rt_bool_t need_schedule = RT_FALSE;
 
        max_value = (rt_uint16_t)((rt_uintptr_t)arg);
        if (max_value > RT_SEM_VALUE_MAX || max_value < 1)
        {
            return -RT_EINVAL;
        }
 
        level = rt_spin_lock_irqsave(&(sem->spinlock));
        if (max_value < sem->value)
        {
            if (!rt_list_isempty(&sem->parent.suspend_thread))
            {
                /* resume all waiting thread */
                rt_susp_list_resume_all(&sem->parent.suspend_thread, RT_ERROR);
                need_schedule = RT_TRUE;
            }
        }
        /* set new value */
        sem->max_value = max_value;
        rt_spin_unlock_irqrestore(&(sem->spinlock), level);
 
        if (need_schedule)
        {
            rt_schedule();
        }
 
        return RT_EOK;
    }
 
    return -RT_ERROR;
}

引用了 rt_semaphore::max_value, rt_ipc_object::parent, rt_semaphore::parent, RT_ASSERT, RT_FALSE, RT_IPC_CMD_RESET, RT_IPC_CMD_SET_VLIMIT, rt_list_isempty(), RT_NULL, RT_Object_Class_Semaphore, rt_object_get_type(), rt_schedule(), RT_SEM_VALUE_MAX, rt_spin_lock_irqsave(), rt_spin_unlock_irqrestore(), rt_susp_list_resume_all(), RT_TRUE, rt_semaphore::spinlock, rt_ipc_object::suspend_thread , 以及 rt_semaphore::value.

函数调用图:

这是这个函数的调用关系图:

RTM_EXPORT() [10/10]

RTM_EXPORT

(

rt_sem_control

)

引用了 rt_sem_control().

函数调用图: