Mutex

Mutex 的协作图:

结构体
struct	OsMux

类型定义
typedef struct OsMux	LosMux

函数
UINT32	LOS_MuxInit (LosMux *mutex, const LosMuxAttr *attr)
	Init a mutex. 更多...
UINT32	LOS_MuxDestroy (LosMux *mutex)
	Destroy a mutex. 更多...
UINT32	LOS_MuxLock (LosMux *mutex, UINT32 timeout)
	Wait to lock a mutex. 更多...
UINT32	LOS_MuxTrylock (LosMux *mutex)
	Try wait to lock a mutex. 更多...
UINT32	LOS_MuxUnlock (LosMux *mutex)
	Release a mutex. 更多...

详细描述

类型定义说明

LosMux

typedef struct OsMux LosMux

Mutex object.

函数说明

LOS_MuxDestroy()

UINT32 LOS_MuxDestroy

(

LosMux *

mutex

)

Destroy a mutex.

Description:

This API is used to delete a specified mutex. Return LOS_OK on deleting successfully, return specific error code otherwise.

注意

• The specific mutex should be created firstly.
• The mutex can be deleted successfully only if no other tasks pend on it.

参数

mutex

[IN] Handle of the mutex to be deleted.

返回值

#LOS_EINVAL	The mutex pointer is NULL.
#LOS_EBUSY	Tasks pended on this mutex.
#LOS_EBADF	The lock has been destroyed or broken.
#LOS_OK	The mutex is successfully deleted.

Dependency:

• los_mux.h: the header file that contains the API declaration.

参见

LOS_MuxInit

Destroy a mutex.

在文件 los_mux.c 第 289 行定义.

{
    UINT32 intSave;
 
    if (mutex == NULL) {
        return LOS_EINVAL;
    }
 
    SCHEDULER_LOCK(intSave);    //保存调度自旋锁
    if (mutex->magic != OS_MUX_MAGIC) {
        SCHEDULER_UNLOCK(intSave);//释放调度自旋锁
        return LOS_EBADF;
    }
 
    if (mutex->muxCount != 0) {
        SCHEDULER_UNLOCK(intSave);//释放调度自旋锁
        return LOS_EBUSY;
    }
 
    (VOID)memset_s(mutex, sizeof(LosMux), 0, sizeof(LosMux));//很简单,全部清0处理.
    SCHEDULER_UNLOCK(intSave);  //释放调度自旋锁
    return LOS_OK;
}

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

LOS_MuxInit()

UINT32 LOS_MuxInit	(	LosMux *	mutex,
		const LosMuxAttr *	attr
	)

Init a mutex.

Description:

This API is used to Init a mutex. A mutex handle is assigned to muxHandle when the mutex is init successfully. Return LOS_OK on creating successful, return specific error code otherwise.

注意

• The total number of mutexes is pre-configured. If there are no available mutexes, the mutex creation fails.

参数

mutex	[IN] Handle pointer of the successfully init mutex.
attr	[IN] The mutex attribute.

返回值

#LOS_EINVAL	The mutex pointer is NULL.
#LOS_OK	The mutex is successfully created.

Dependency:

• los_mux.h: the header file that contains the API declaration.

参见

LOS_MuxDestroy

Init a mutex.

在文件 los_mux.c 第 262 行定义.

{
    UINT32 intSave;
 
    if (mutex == NULL) {
        return LOS_EINVAL;
    }
 
    if (attr == NULL) {
        (VOID)LOS_MuxAttrInit(&mutex->attr);//属性初始化
    } else {
        (VOID)memcpy_s(&mutex->attr, sizeof(LosMuxAttr), attr, sizeof(LosMuxAttr));//把attr 拷贝到 mutex->attr
    }
 
    if (OsCheckMutexAttr(&mutex->attr) != LOS_OK) {//检查属性
        return LOS_EINVAL;
    }
 
    SCHEDULER_LOCK(intSave);        //拿到调度自旋锁
    mutex->muxCount = 0;            //锁定互斥量的次数
    mutex->owner = NULL;            //谁持有该锁
    LOS_ListInit(&mutex->muxList);  //互斥量双循环链表
    mutex->magic = OS_MUX_MAGIC;    //固定标识,互斥锁的魔法数字
    SCHEDULER_UNLOCK(intSave);      //释放调度自旋锁
    return LOS_OK;
}

函数调用图:

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

LOS_MuxLock()

UINT32 LOS_MuxLock	(	LosMux *	mutex,
		UINT32	timeout
	)

Wait to lock a mutex.

Description:

This API is used to wait for a specified period of time to lock a mutex.

注意

• The specific mutex should be created firstly.
• The function fails if the mutex that is waited on is already locked by another thread when the task scheduling is disabled.
• Do not wait on a mutex during an interrupt.
• The priority inheritance protocol is supported. If a higher-priority thread is waiting on a mutex, it changes the priority of the thread that owns the mutex to avoid priority inversion.
• A recursive mutex can be locked more than once by the same thread.
• Do not call this API in software timer callback.

参数

mutex	[IN] Handle of the mutex to be waited on.
timeout	[IN] Waiting time. The value range is [0, LOS_WAIT_FOREVER](unit: Tick).

返回值

#LOS_EINVAL	The mutex pointer is NULL, The timeout is zero or Lock status error.
#LOS_EINTR	The mutex is being locked during an interrupt.
#LOS_EBUSY	Tasks pended on this mutex.
#LOS_EBADF	The lock has been destroyed or broken.
#LOS_EDEADLK	Mutex error check failed or System locked task scheduling.
#LOS_ETIMEDOUT	The mutex waiting times out.
#LOS_OK	The mutex is successfully locked.

Dependency:

• los_mux.h: the header file that contains the API declaration.

参见

LOS_MuxInit | LOS_MuxUnlock

Wait to lock a mutex.

在文件 los_mux.c 第 437 行定义.

{
    LosTaskCB *runTask = NULL;
    UINT32 intSave;
    UINT32 ret;
 
    if (mutex == NULL) {
        return LOS_EINVAL;
    }
 
    if (OS_INT_ACTIVE) {
        return LOS_EINTR;
    }
 
    runTask = (LosTaskCB *)OsCurrTaskGet();//获取当前任务
    /* DO NOT Call blocking API in system tasks */
    if (runTask->taskStatus & OS_TASK_FLAG_SYSTEM_TASK) {//不要在内核任务里用mux锁
        PRINTK("Warning: DO NOT call %s in system tasks.\n", __FUNCTION__);
        OsBackTrace();//打印task信息
    }
 
    SCHEDULER_LOCK(intSave);//调度自旋锁
    ret = OsMuxLockUnsafe(mutex, timeout);//如果任务没拿到锁,将进入阻塞队列一直等待,直到timeout或者持锁任务释放锁时唤醒它 
    SCHEDULER_UNLOCK(intSave);
    return ret;
}

函数调用图:

LOS_MuxTrylock()

UINT32 LOS_MuxTrylock

(

LosMux *

mutex

)

Try wait to lock a mutex.

Description:

This API is used to wait for a specified period of time to lock a mutex.

注意

• The specific mutex should be created firstly.
• The function fails if the mutex that is waited on is already locked by another thread when the task scheduling is disabled.
• Do not wait on a mutex during an interrupt.
• The priority inheritance protocol is supported. If a higher-priority thread is waiting on a mutex, it changes the priority of the thread that owns the mutex to avoid priority inversion.
• A recursive mutex can be locked more than once by the same thread.
• Do not call this API in software timer callback.

参数

mutex

[IN] Handle of the mutex to be waited on.

返回值

#LOS_EINVAL	The mutex pointer is NULL or Lock status error.
#LOS_EINTR	The mutex is being locked during an interrupt.
#LOS_EBUSY	Tasks pended on this mutex.
#LOS_EBADF	The lock has been destroyed or broken.
#LOS_EDEADLK	Mutex error check failed or System locked task scheduling.
#LOS_ETIMEDOUT	The mutex waiting times out.
#LOS_OK	The mutex is successfully locked.

Dependency:

• los_mux.h: the header file that contains the API declaration.

参见

LOS_MuxInit | LOS_MuxUnlock

Try wait to lock a mutex.

在文件 los_mux.c 第 464 行定义.

{
    LosTaskCB *runTask = NULL;
    UINT32 intSave;
    UINT32 ret;
 
    if (mutex == NULL) {
        return LOS_EINVAL;
    }
 
    if (OS_INT_ACTIVE) {
        return LOS_EINTR;
    }
 
    runTask = (LosTaskCB *)OsCurrTaskGet();//获取当前执行的任务
    /* DO NOT Call blocking API in system tasks */
    if (runTask->taskStatus & OS_TASK_FLAG_SYSTEM_TASK) {//系统任务不能
        PRINTK("Warning: DO NOT call %s in system tasks.\n", __FUNCTION__);
        OsBackTrace();
    }
 
    SCHEDULER_LOCK(intSave);
    ret = OsMuxTrylockUnsafe(mutex, 0);//timeout = 0,不等待,没拿到锁就算了
    SCHEDULER_UNLOCK(intSave);
    return ret;
}

函数调用图:

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

LOS_MuxUnlock()

UINT32 LOS_MuxUnlock

(

LosMux *

mutex

)

Release a mutex.

Description:

This API is used to release a specified mutex.

注意

• The specific mutex should be created firstly.
• Do not release a mutex during an interrupt.
• If a recursive mutex is locked for many times, it must be unlocked for the same times to be released.

参数

mutex

[IN] Handle of the mutex to be released.

返回值

#LOS_EINVAL	The mutex pointer is NULL, The timeout is zero or Lock status error.
#LOS_EINTR	The mutex is being locked during an interrupt.
#LOS_EBUSY	Tasks pended on this mutex.
#LOS_EBADF	The lock has been destroyed or broken.
#LOS_EDEADLK	Mutex error check failed or System locked task scheduling.
#LOS_ETIMEDOUT	The mutex waiting times out.
#LOS_OK	The mutex is successfully locked.

Dependency:

• los_mux.h: the header file that contains the API declaration.

参见

LOS_MuxInit | LOS_MuxLock

Release a mutex.

在文件 los_mux.c 第 559 行定义.

{
    LosTaskCB *runTask = NULL;
    BOOL needSched = FALSE;
    UINT32 intSave;
    UINT32 ret;
 
    if (mutex == NULL) {
        return LOS_EINVAL;
    }
 
    if (OS_INT_ACTIVE) {
        return LOS_EINTR;
    }
 
    runTask = (LosTaskCB *)OsCurrTaskGet();//获取当前任务
    /* DO NOT Call blocking API in system tasks */
    if (runTask->taskStatus & OS_TASK_FLAG_SYSTEM_TASK) {//不能在系统任务里调用,因为很容易让系统任务发生死锁
        PRINTK("Warning: DO NOT call %s in system tasks.\n", __FUNCTION__);
        OsBackTrace();
    }
 
    SCHEDULER_LOCK(intSave);
    ret = OsMuxUnlockUnsafe(runTask, mutex, &needSched);
    SCHEDULER_UNLOCK(intSave);
    if (needSched == TRUE) {//需要调度的情况
        LOS_MpSchedule(OS_MP_CPU_ALL);//向所有CPU发送调度指令
        LOS_Schedule();//发起调度
    }
    return ret;
}

函数调用图: