From 1d2fde8d73ec03ba6d7cc2538765544f30684daf Mon Sep 17 00:00:00 2001 From: Troy Date: Tue, 30 Apr 2024 12:16:57 +0800 Subject: [PATCH] Add comments for all functions in components/libc/posix/ipc/mqueue.c --- components/libc/posix/ipc/mqueue.c | 162 ++++++++++++++++++++++++++++- 1 file changed, 161 insertions(+), 1 deletion(-) diff --git a/components/libc/posix/ipc/mqueue.c b/components/libc/posix/ipc/mqueue.c index a452092875..17449662b0 100644 --- a/components/libc/posix/ipc/mqueue.c +++ b/components/libc/posix/ipc/mqueue.c @@ -4,13 +4,29 @@ * SPDX-License-Identifier: Apache-2.0 * * Change Logs: - * Date Author Notes + * Date Author Notes + * 2023-07-20 zmq810150896 first version + * 2024-04-30 TroyMitchell Add comments for all functions */ #include #include #include "mqueue.h" +/** + * @brief Sets the attributes of a message queue. + * @param id Identifier of the message queue. + * @param mqstat Pointer to a struct mq_attr containing the new attributes (ignored). + * @param omqstat Pointer to a struct mq_attr where the old attributes will be stored. + * @return Upon successful completion, returns 0; otherwise, returns -1 and sets errno to indicate the error. + * + * @note This function sets the attributes of the message queue specified by id. + * The new attributes are provided in the mqstat parameter, but this implementation ignores it. + * Instead, the function calls mq_getattr() to retrieve the current attributes of the message queue + * and stores them in the struct mq_attr pointed to by omqstat. + * If mqstat is RT_NULL, the function behaves as a query and retrieves the attributes without setting new values. + * If an error occurs during the operation, errno is set to indicate the error, and the function returns -1. + */ int mq_setattr(mqd_t id, const struct mq_attr *mqstat, struct mq_attr *omqstat) @@ -24,6 +40,21 @@ int mq_setattr(mqd_t id, } RTM_EXPORT(mq_setattr); +/** + * @brief Gets the attributes of a message queue. + * @param id Identifier of the message queue. + * @param mqstat Pointer to a struct mq_attr where the attributes will be stored. + * @return Upon successful completion, returns 0; otherwise, returns -1 and sets errno to indicate the error. + * + * @note This function retrieves the attributes of the message queue specified by id. + * The attributes include the maximum number of messages that can be queued (mq_maxmsg), + * the maximum size of each message (mq_msgsize), the number of messages currently in the queue (mq_curmsgs), + * and the flags associated with the queue (mq_flags). + * The attributes are stored in the struct mq_attr pointed to by mqstat. + * If the message queue identified by id does not exist or if mqstat is a null pointer, errno is set to EBADF, + * indicating a bad file descriptor, and the function returns -1. + * Otherwise, the function retrieves the attributes from the message queue and stores them in mqstat, returning 0 to indicate success. + */ int mq_getattr(mqd_t id, struct mq_attr *mqstat) { rt_mq_t mq; @@ -45,6 +76,30 @@ int mq_getattr(mqd_t id, struct mq_attr *mqstat) } RTM_EXPORT(mq_getattr); +/** + * @brief Opens or creates a message queue. + * @param name Name of the message queue. + * @param oflag Flags indicating the access mode and creation options (O_CREAT, O_EXCL, etc.). + * @param ... Additional arguments for creation options (mode, attr) (ignored). + * @return Upon successful completion, returns a message queue descriptor (mqd_t); + * otherwise, returns (mqd_t)(-1) and sets errno to indicate the error. + * + * @note This function opens or creates a message queue specified by name with the specified flags. + * If the name starts with '/', the leading '/' is ignored. + * The function then checks the length of the name and verifies if it exceeds the maximum allowed length. + * If the name is too long, errno is set to ENAMETOOLONG, indicating a name too long error. + * Next, the function attempts to find the message queue file corresponding to the name. + * If the file exists and O_CREAT and O_EXCL flags are both set, indicating exclusive creation, + * errno is set to EEXIST, indicating that the file already exists. + * If the file does not exist and O_CREAT flag is set, the function checks the message queue attributes. + * If the maximum number of messages (mq_maxmsg) in the attributes is less than or equal to 0, + * errno is set to EINVAL, indicating an invalid argument for the maximum number of messages. + * If the file does not exist and O_CREAT flag is not set, errno is set to ENOENT, indicating no such file or directory. + * If the message queue needs to be created (O_CREAT flag set), a new mqueue_file structure is allocated and initialized + * with the specified message queue attributes, and it is inserted into the message queue filesystem. + * Finally, the function constructs the path to the message queue device file, opens it with the specified flags, + * and returns the file descriptor as a message queue descriptor (mqd_t). + */ mqd_t mq_open(const char *name, int oflag, ...) { int mq_fd; @@ -115,6 +170,26 @@ mqd_t mq_open(const char *name, int oflag, ...) } RTM_EXPORT(mq_open); +/** + * @brief Receives a message from a message queue. + * @param id Message queue descriptor. + * @param msg_ptr Pointer to the buffer where the received message will be stored. + * @param msg_len Maximum size of the message buffer. + * @param msg_prio Pointer to an unsigned integer where the priority of the received message will be stored (ignored). + * @return Upon successful completion, returns the number of bytes received; + * otherwise, returns -1 and sets errno to indicate the error. + * + * @note This function receives a message from the message queue identified by id. + * The received message is stored in the buffer pointed to by msg_ptr, with a maximum size of msg_len bytes. + * The priority of the received message is stored in the unsigned integer pointed to by msg_prio (ignored in this implementation). + * If either the message queue identified by id or the msg_ptr buffer is a null pointer, errno is set to EINVAL, + * indicating an invalid argument, and the function returns -1. + * The function then attempts to receive a message from the message queue using the rt_mq_recv_prio() function + * with an infinite timeout and uninterruptible mode. + * If a message is successfully received, the function returns the number of bytes received. + * If an error occurs during the receive operation, errno is set to EBADF, indicating a bad file descriptor, + * and the function returns -1. + */ ssize_t mq_receive(mqd_t id, char *msg_ptr, size_t msg_len, unsigned *msg_prio) { rt_mq_t mq; @@ -137,6 +212,26 @@ ssize_t mq_receive(mqd_t id, char *msg_ptr, size_t msg_len, unsigned *msg_prio) } RTM_EXPORT(mq_receive); +/** + * @brief Sends a message to a message queue. + * @param id Message queue descriptor. + * @param msg_ptr Pointer to the buffer containing the message to be sent. + * @param msg_len Size of the message to be sent. + * @param msg_prio Priority of the message to be sent. + * @return Upon successful completion, returns 0; + * otherwise, returns -1 and sets errno to indicate the error. + * + * @note This function sends a message to the message queue identified by id. + * The message to be sent is contained in the buffer pointed to by msg_ptr, with a size of msg_len bytes. + * The priority of the message is specified by the msg_prio parameter. + * If either the message queue identified by id or the msg_ptr buffer is a null pointer, errno is set to EINVAL, + * indicating an invalid argument, and the function returns -1. + * The function then attempts to send the message to the message queue using the rt_mq_send_wait_prio() function + * with zero timeout and uninterruptible mode. + * If the message is successfully sent, the function returns 0. + * If an error occurs during the send operation, errno is set to EBADF, indicating a bad file descriptor, + * and the function returns -1. + */ int mq_send(mqd_t id, const char *msg_ptr, size_t msg_len, unsigned msg_prio) { rt_mq_t mq; @@ -160,6 +255,31 @@ int mq_send(mqd_t id, const char *msg_ptr, size_t msg_len, unsigned msg_prio) } RTM_EXPORT(mq_send); +/** + * @brief Receives a message from a message queue with a timeout. + * @param id Message queue descriptor. + * @param msg_ptr Pointer to the buffer where the received message will be stored. + * @param msg_len Maximum size of the message buffer. + * @param msg_prio Pointer to an unsigned integer where the priority of the received message will be stored. + * @param abs_timeout Pointer to a struct timespec specifying the absolute timeout value (ignored if null). + * @return Upon successful completion, returns the number of bytes received; + * otherwise, returns -1 and sets errno to indicate the error. + * + * @note This function receives a message from the message queue identified by id with a specified timeout. + * The received message is stored in the buffer pointed to by msg_ptr, with a maximum size of msg_len bytes. + * The priority of the received message is stored in the unsigned integer pointed to by msg_prio. + * If either the message queue identified by id or the msg_ptr buffer is a null pointer, errno is set to EINVAL, + * indicating an invalid argument, and the function returns -1. + * The function then converts the absolute timeout value specified by abs_timeout to system ticks, + * or sets the timeout to RT_WAITING_FOREVER if abs_timeout is null. + * It attempts to receive a message from the message queue using the rt_mq_recv_prio() function + * with the specified timeout and uninterruptible mode. + * If a message is successfully received, the function returns the number of bytes received. + * If the receive operation times out, errno is set to ETIMEDOUT, indicating a timeout error. + * If the received message is too large for the specified buffer, errno is set to EMSGSIZE, indicating a message too large error. + * If an unknown error occurs during the receive operation, errno is set to EBADMSG, indicating a bad message error, + * and the function returns -1. + */ ssize_t mq_timedreceive(mqd_t id, char *msg_ptr, size_t msg_len, @@ -199,6 +319,23 @@ ssize_t mq_timedreceive(mqd_t id, } RTM_EXPORT(mq_timedreceive); +/** + * @brief Sends a message to a message queue with a timeout (not supported). + * @param id Message queue descriptor. + * @param msg_ptr Pointer to the buffer containing the message to be sent. + * @param msg_len Size of the message to be sent. + * @param msg_prio Priority of the message to be sent. + * @param abs_timeout Pointer to a struct timespec specifying the absolute timeout value (ignored). + * @return Upon successful completion, returns 0; + * otherwise, returns -1 and sets errno to indicate the error. + * + * @note This function attempts to send a message to the message queue identified by id with a specified timeout, + * but timed send is not supported in the RT-Thread environment. + * Therefore, the function simply delegates the message sending operation to the mq_send() function, + * which does not involve a timeout. + * The abs_timeout parameter is ignored, and the message is sent without waiting for a timeout to occur. + * The function returns the result of the mq_send() function, which indicates whether the message was successfully sent. + */ int mq_timedsend(mqd_t id, const char *msg_ptr, size_t msg_len, @@ -210,6 +347,18 @@ int mq_timedsend(mqd_t id, } RTM_EXPORT(mq_timedsend); +/** + * @brief Registers for notification when a message is available in a message queue (not supported). + * @param id Message queue descriptor. + * @param notification Pointer to a struct sigevent specifying the notification settings (ignored). + * @return Upon successful completion, returns 0; + * otherwise, returns -1 and sets errno to indicate the error. + * + * @note This function attempts to register for notification when a message is available in the message queue identified by id. + * However, message queue notification is not supported in the RT-Thread environment. + * Therefore, this function simply sets errno to EBADF, indicating a bad file descriptor, + * and returns -1 to indicate that the operation is not supported. + */ int mq_notify(mqd_t id, const struct sigevent *notification) { rt_mq_t mq; @@ -227,6 +376,17 @@ int mq_notify(mqd_t id, const struct sigevent *notification) } RTM_EXPORT(mq_notify); +/** + * @brief Closes a message queue descriptor. + * @param id Message queue descriptor to be closed. + * @return Upon successful completion, returns 0; + * otherwise, returns -1 and sets errno to indicate the error. + * + * @note This function closes the message queue descriptor specified by id. + * It delegates the closing operation to the close() function, which closes the file descriptor associated with the message queue. + * If the close operation is successful, the function returns 0. + * If an error occurs during the close operation, errno is set to indicate the error, and the function returns -1. + */ int mq_close(mqd_t id) { return close(id);