Message queue

结构体
struct	mq_attr

类型定义
typedef UINTPTR	mqd_t

函数
mqd_t	mq_open (const char *mqName, int openFlag,...)
int	mq_close (mqd_t personal)
int	mq_unlink (const char *mqName)
int	mq_send (mqd_t personal, const char *msg, size_t msgLen, unsigned int msgPrio)
ssize_t	mq_receive (mqd_t personal, char *msg, size_t msgLen, unsigned int *msgPrio)
int	mq_getsetattr (mqd_t personal, const struct mq_attr *mqSetAttr, struct mq_attr *MqOldAttr)
int	mq_timedsend (mqd_t personal, const char *msg, size_t msgLen, unsigned int msgPrio, const struct timespec *absTimeout)
ssize_t	mq_timedreceive (mqd_t personal, char *msg, size_t msgLen, unsigned int *msgPrio, const struct timespec *absTimeout)

详细描述

类型定义说明

mqd_t

typedef UINTPTR mqd_t

Handle type of a message queue

在文件 mqueue.h 第 127 行定义.

函数说明

mq_close()

int mq_close

(

mqd_t

personal

)

Description:

This API is used to close a message queue that has a specified descriptor.

注意

• If the message queue is empty, it will be reclaimed, which is similar to when mq_unlink is called.

参数

personal

[IN] Message queue descriptor.

返回值

0	The message queue is successfully closed.
-1	The message queue fails to be closed, with either of the following error codes in errno.

Errors

• EBADF: Invalid message queue descriptor.
• EAGAIN: Failed to delete the message queue.
• EFAULT: Failed to free the message queue.
• EINVAL: Invalid parameter.

Dependency:

• mqueue.h

参见

mq_open

在文件 mqueue.c 第 550 行定义.

{
    INT32 ret = -1;
    struct mqpersonal *privateMqPersonal = NULL;
 
    (VOID)pthread_mutex_lock(&g_mqueueMutex);
 
    /* Get the personal sysFd and reset personal fd -1 */
    privateMqPersonal = MqGetPrivDataBuff(personal);
    if (privateMqPersonal == NULL) {
        goto OUT_UNLOCK;
    }
 
    if (privateMqPersonal->mq_status != MQ_USE_MAGIC) {
        errno = EBADF;
        goto OUT_UNLOCK;
    }
 
    if (!MqTryClose(privateMqPersonal)) {
        ret = 0;
        goto OUT_UNLOCK;
    }
 
    ret = DoMqueueClose(privateMqPersonal);
    if (ret < 0) {
        goto OUT_UNLOCK;
    }
    MqFreeSysFd(personal);
 
OUT_UNLOCK:
    (VOID)pthread_mutex_unlock(&g_mqueueMutex);
    return ret;
}

函数调用图:

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

mq_getsetattr()

int mq_getsetattr	(	mqd_t	personal,
		const struct mq_attr *	mqSetAttr,
		struct mq_attr *	MqOldAttr
	)

Description:

This API is used to obtain or modify attributes of the message queue that has a specified descriptor.

注意

• The mq_maxmsg, mq_msgsize, and mq_curmsgs attributes are not modified in the message queue attribute setting.

参数

personal	[IN] Message queue descriptor.
mqSetAttr	[IN] New attribute of the message queue.
MqOldAttr	[OUT] Old attribute of the message queue.

返回值

0	The message queue attributes are successfully set or get.
-1	The message queue attributes fail to be set or get, with either of the following error codes in the errno.

Errors

• EBADF: Invalid message queue.
• EINVAL: Invalid parameter.

Dependency:

• mqueue.h

参见

sys_mq_getsetattr

在文件 mqueue.c 第 648 行定义.

{
    if (new == NULL) {
        return OsMqGetAttr(mqd, old);
    }
    return OsMqSetAttr(mqd, new, old);
}

函数调用图:

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

mq_open()

mqd_t mq_open	(	const char *	mqName,
		int	openFlag,
			...
	)

Description:

This API is used to open an existed message queue that has a specified name or create a new message queue.

注意

• A message queue does not restrict the read and write permissions.
• The length of mqueue name must less than 256.
• This operation and closed mqueue scheduling must be used in coordination to release the resource.
• The parameter "mode" is not supported.
• The "mq_curmsgs" member of the mq_attr structure is not supported.

参数

mqName	[IN] Message queue name.
openFlag	[IN] Permission attributes of the message queue. The value range is [O_RDONLY, O_WRONLY, O_RDWR, O_CREAT, O_EXCL, O_NONBLOCK].
mode	[IN] Message queue mode (variadic argument). When oflag is O_CREAT, it requires two additional arguments: mode, which shall be of type mode_t, and attr, which shall be a pointer to an mq_attr structure.
attr	[IN] Message queue attribute (variadic argument).

返回值

mqd_t	The message queue is successfully opened or created.
(mqd_t)-1	The message queue fails to be opened or created, with any of the following error codes in errno.

Errors

• ENOENT: O_CREAT flag is not set for oflag, and the message queue specified by name does not exist.
• EEXIST: Both O_CREAT and O_EXCL are set for oflag, but the message queue specified by name already exists.
• EINVAL: invalid parameter.
• ENFILE: The number of opened message queues exceeds the maximum limit.
• ENOSPC: insufficient memory.
• ENAMETOOLONG: The message queue name specified by name is too long.

Dependency:

• mqueue.h

参见

mq_close

在文件 mqueue.c 第 486 行定义.

{
    struct mqarray *mqueueCB = NULL;
    struct mqpersonal *privateMqPersonal = (struct mqpersonal *)-1;
    struct mq_attr *attr = NULL;
    struct mq_attr defaultAttr = { 0, MQ_MAX_MSG_NUM, MQ_MAX_MSG_LEN, 0 };
    va_list ap;
    int sysFd;
    mqd_t mqFd = -1;
    unsigned int mode = 0;
 
    if (MqNameCheck(mqName) == -1) {
        return (mqd_t)-1;
    }
 
    (VOID)pthread_mutex_lock(&g_mqueueMutex);
    mqueueCB = GetMqueueCBByName(mqName);
    if ((UINT32)openFlag & (UINT32)O_CREAT) {
        if (mqueueCB != NULL) {
            if (((UINT32)openFlag & (UINT32)O_EXCL)) {
                errno = EEXIST;
                goto OUT;
            }
            privateMqPersonal = DoMqueueOpen(mqueueCB, openFlag);
        } else {
            va_start(ap, openFlag);
            mode = va_arg(ap, unsigned int);
            attr = va_arg(ap, struct mq_attr *);
            va_end(ap);
 
            if (GetMqueueAttr(&defaultAttr, attr)) {
                goto OUT;
            }
            privateMqPersonal = DoMqueueCreate(&defaultAttr, mqName, openFlag, mode);
        }
        /* Set mode data bit ,just for the first node */
        if (MqueueModeAnalysisSet(privateMqPersonal)) {
            if ((INT32)(UINTPTR)privateMqPersonal > 0) {
                (VOID)DoMqueueClose(privateMqPersonal);
            }
            goto OUT;
        }
    } else {
        if (GetPermissionOfVisitor(mqueueCB)) {
            goto OUT;
        }
        privateMqPersonal = DoMqueueOpen(mqueueCB, openFlag);
    }
 
    if ((INT32)(UINTPTR)privateMqPersonal > 0) {
        /* alloc sysFd */
        sysFd = MqAllocSysFd(MAX_MQ_FD, privateMqPersonal);
        if (sysFd == -1) {
            /* there are no more mq sysFd to use, close the personal */
            (VOID)DoMqueueClose(privateMqPersonal);
            errno = ENFILE;
        }
        mqFd = (mqd_t)sysFd;
    }
OUT:
    (VOID)pthread_mutex_unlock(&g_mqueueMutex);
    return mqFd;
}

函数调用图:

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

mq_receive()

ssize_t mq_receive	(	mqd_t	personal,
		char *	msg,
		size_t	msgLen,
		unsigned int *	msgPrio
	)

Description:

This API is used to remove the oldest message from the message queue that has a specified descriptor, and puts it in the buffer pointed to by msg_ptr.

注意

• Priority-based message processing is not supported.
• The msg_len should be same to the length of string which msg_ptr point to.

参数

personal	[IN] Message queue descriptor.
msg	[IN] Pointer to the message content to be received.
msgLen	[IN] Length of the message to be received.
msgPrio	[OUT] Priority of the message to be received because priority-based message processing is not supported, this parameter is useless).

返回值

0	The message is successfully received.
-1	The message fails to be received, with any of the following error codes in the errno.

Errors

• EINTR: An interrupt is in progress while the message is being received.
• EBADF: The message queue is invalid or not readable.
• EAGAIN: The message queue is empty.
• EINVAL: invalid parameter.
• EMSGSIZE: The message to be received is too long.
• ETIMEDOUT: The operaton times out.

Dependency:

• mqueue.h

参见

mq_send

在文件 mqueue.c 第 863 行定义.

{
    return mq_timedreceive(personal, msg_ptr, msg_len, msg_prio, NULL);
}

函数调用图:

mq_send()

int mq_send	(	mqd_t	personal,
		const char *	msg,
		size_t	msgLen,
		unsigned int	msgPrio
	)

Description:

This API is used to put a message with specified message content and length into a message queue that has a specified descriptor.

注意

• Priority-based message processing is not supported.
• The msg_len should be same to the length of string which msg_ptr point to.

参数

personal	[IN] Message queue descriptor.
msg	[IN] Pointer to the message content to be sent.
msgLen	[IN] Length of the message to be sent.
msgPrio	[IN] Priority of the message to be sent (the value of this parameter must be 0 because priority-based message sending is not supported. If the value is not 0, this API will cease to work.)

返回值

0	The message is successfully sent.
-1	The message fails to be sent, with any of the following error codes in errno.

Errors

• EINTR: An interrupt is in progress while the message is being sent.
• EBADF: The message queue is invalid or not writable.
• EAGAIN: The message queue is full.
• EINVAL: Invalid parameter.
• ENOSPC: Insufficient memory.
• EMSGSIZE: The message to be sent is too long.
• EOPNOTSUPP: The operation is not supported.
• ETIMEDOUT: The operation times out.

Dependency:

• mqueue.h

参见

mq_receive

在文件 mqueue.c 第 858 行定义.

{
    return mq_timedsend(personal, msg_ptr, msg_len, msg_prio, NULL);
}

函数调用图:

mq_timedreceive()

ssize_t mq_timedreceive	(	mqd_t	personal,
		char *	msg,
		size_t	msgLen,
		unsigned int *	msgPrio,
		const struct timespec *	absTimeout
	)

Description:

This API is used to obtain a message with specified message content and length from a message queue message that has a specified descriptor.

注意

• Priority-based message processing is not supported.
• The expiry time must be later than the current time.
• The wait time is a relative time.
• The msg_len should be same to the length of string which msg_ptr point to.

参数

personal	[IN] Message queue descriptor.
msg	[IN] Pointer to the message content to be received.
msgLen	[IN] Length of the message to be received.
msgPrio	[OUT] Priority of the message to be received (because priority-based message processing is not supported, this parameter is useless ).
absTimeout	[IN] Scheduled time at which the messagewill be received. If the value is 0, the message is an instant message.

返回值

0	The message is successfully received.
-1	The message fails to be received, with any of the following error codes in errno.

Errors

• EINTR: An interrupt is in progress while the message is being received.
• EBADF: The message queue is invalid or not readable.
• EAGAIN: The message queue is empty.
• EINVAL: invalid parameter.
• EMSGSIZE: The message to be received is too long.
• ETIMEDOUT: The operation times out.

Dependency:

• mqueue.h

参见

mq_send

在文件 mqueue.c 第 801 行定义.

{
    UINT32 mqueueID, err;
    UINT32 receiveLen;
    UINT64 absTicks;
    struct mqarray *mqueueCB = NULL;
    struct mqpersonal *privateMqPersonal = NULL;
 
    if (!MqParamCheck(personal, msg, msgLen)) {
        goto ERROUT;
    }
 
    if (msgPrio != NULL) {
        *msgPrio = 0;
    }
 
    (VOID)pthread_mutex_lock(&g_mqueueMutex);
    privateMqPersonal = MqGetPrivDataBuff(personal);
    if (privateMqPersonal == NULL || privateMqPersonal->mq_status != MQ_USE_MAGIC) {
        errno = EBADF;
        goto ERROUT_UNLOCK;
    }
 
    mqueueCB = privateMqPersonal->mq_posixdes;
    if (msgLen < (size_t)(mqueueCB->mqcb->queueSize - sizeof(UINT32))) {
        errno = EMSGSIZE;
        goto ERROUT_UNLOCK;
    }
 
    if (((UINT32)privateMqPersonal->mq_flags & (UINT32)O_WRONLY) == (UINT32)O_WRONLY) {
        errno = EBADF;
        goto ERROUT_UNLOCK;
    }
 
    if (ConvertTimeout(privateMqPersonal->mq_flags, absTimeout, &absTicks) == -1) {
        goto ERROUT_UNLOCK;
    }
 
    receiveLen = msgLen;
    mqueueID = mqueueCB->mq_id;
    (VOID)pthread_mutex_unlock(&g_mqueueMutex);
 
    err = LOS_QueueReadCopy(mqueueID, (VOID *)msg, &receiveLen, (UINT32)absTicks);
    if (map_errno(err) == ENOERR) {
        return (ssize_t)receiveLen;
    } else {
        goto ERROUT;
    }
 
ERROUT_UNLOCK:
    (VOID)pthread_mutex_unlock(&g_mqueueMutex);
ERROUT:
    return -1;
}

函数调用图:

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

mq_timedsend()

int mq_timedsend	(	mqd_t	personal,
		const char *	msg,
		size_t	msgLen,
		unsigned int	msgPrio,
		const struct timespec *	absTimeout
	)

Description:

This API is used to put a message with specified message content and length into a message queue that has a descriptor at a scheduled time.

注意

• Priority-based message processing is not supported.
• The expiry time must be later than the current time.
• The wait time is a relative time.
• The msg_len should be same to the length of string which msg_ptr point to.

参数

mqdes	[IN] Message queue descriptor.
msg	[IN] Pointer to the message content to be sent.
msgLen	[IN] Length of the message to be sent.
msgPrio	[IN] Priority of the message to be sent (the value of this parameter must be 0 because priority-based message processing is not supported).
absTimeout	[IN] Scheduled time at which the message will be sent. If the value is 0, the message is an instant message.

返回值

0	The message is successfully sent.
-1	The message fails to be sent, with any of the following error codes in errno.

Errors

• EINTR: An interrupt is in progress while the message is being sent.
• EBADF: The message queue is invalid or not writable.
• EAGAIN: The message queue is full.
• EINVAL: Invalid parameter.
• EMSGSIZE: The message to be sent is too long.
• EOPNOTSUPP: The operation is not supported.
• ETIMEDOUT: The operation times out.

Dependency:

• mqueue.h

参见

mq_receive

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

{
    UINT32 mqueueID, err;
    UINT64 absTicks;
    struct mqarray *mqueueCB = NULL;
    struct mqpersonal *privateMqPersonal = NULL;
 
    OS_MQ_GOTO_ERROUT_IF(!MqParamCheck(personal, msg, msgLen), errno);
    OS_MQ_GOTO_ERROUT_IF(msgPrio > (MQ_PRIO_MAX - 1), EINVAL);
 
    (VOID)pthread_mutex_lock(&g_mqueueMutex);
    privateMqPersonal = MqGetPrivDataBuff(personal);
 
    OS_MQ_GOTO_ERROUT_UNLOCK_IF(privateMqPersonal == NULL || privateMqPersonal->mq_status != MQ_USE_MAGIC, EBADF);
 
    mqueueCB = privateMqPersonal->mq_posixdes;
    OS_MQ_GOTO_ERROUT_UNLOCK_IF(msgLen > (size_t)(mqueueCB->mqcb->queueSize - sizeof(UINT32)), EMSGSIZE);
 
    OS_MQ_GOTO_ERROUT_UNLOCK_IF((((UINT32)privateMqPersonal->mq_flags & (UINT32)O_WRONLY) != (UINT32)O_WRONLY) &&
                                (((UINT32)privateMqPersonal->mq_flags & (UINT32)O_RDWR) != (UINT32)O_RDWR),
                                EBADF);
 
    OS_MQ_GOTO_ERROUT_UNLOCK_IF(ConvertTimeout(privateMqPersonal->mq_flags, absTimeout, &absTicks) == -1, errno);
    mqueueID = mqueueCB->mq_id;
    (VOID)pthread_mutex_unlock(&g_mqueueMutex);
 
    if (LOS_ListEmpty(&mqueueCB->mqcb->readWriteList[OS_QUEUE_READ])) {
        MqSendNotify(mqueueCB);
    }
 
    err = LOS_QueueWriteCopy(mqueueID, (VOID *)msg, (UINT32)msgLen, (UINT32)absTicks);
    if (map_errno(err) != ENOERR) {
        goto ERROUT;
    }
    return 0;
ERROUT_UNLOCK:
    (VOID)pthread_mutex_unlock(&g_mqueueMutex);
ERROUT:
    return -1;
}

函数调用图:

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

mq_unlink()

int mq_unlink

(

const char *

mqName

)

Description:

This API is used to remove a message queue that has a specified name.

注意

• If the message queue is empty, it will be reclaimed, which is similar to when mq_close is called.
• The length of mqueue name must less than 256.

参数

mqName

[IN] Message queue name.

返回值

0	The message queue is successfully removed.
-1	The message queue fails to be removed, with any of the following error codes in errno.

Errors

• ENOENT: The message queue specified by name does not exist.
• EAGAIN: Failed to delete the message queue.
• EBUSY: The message queue to be removed is being used.
• EINVAL: Invalid parameter.
• ENAMETOOLONG: The name of mqueue is too long.

Dependency:

• mqueue.h

参见

mq_close

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

{
    INT32 ret = 0;
    struct mqarray *mqueueCB = NULL;
 
    if (MqNameCheck(mqName) == -1) {
        return -1;
    }
 
    (VOID)pthread_mutex_lock(&g_mqueueMutex);
    mqueueCB = GetMqueueCBByName(mqName);
    if (mqueueCB == NULL) {
        errno = ENOENT;
        goto ERROUT_UNLOCK;
    }
 
    if (mqueueCB->mq_personal != NULL) {
        mqueueCB->unlinkflag = TRUE;
    } else if (mqueueCB->unlink_ref == 0) {
        ret = DoMqueueDelete(mqueueCB);
    }
 
    (VOID)pthread_mutex_unlock(&g_mqueueMutex);
    return ret;
 
ERROUT_UNLOCK:
    (VOID)pthread_mutex_unlock(&g_mqueueMutex);
    return -1;
}

函数调用图:

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