#4508 closed defect (fixed)

rtems_message_queue_receive(): flush() does not release waiting tasks

Reported by: Frank Kuehndel Owned by: Sebastian Huber
Priority: low Milestone: 6.1
Component: doc Version: 6
Severity: trivial Keywords: qualification
Cc: Blocked By:
Blocking:

Description

The RTEMS Classic API Guide https://docs.rtems.org/branches/master/c-user/index.html in Message ManagerDirectives → section 14.4.8 rtems_message_queue_receive() says:

RTEMS_UNSATISFIED:

The queue was flushed while the calling task was waiting to receive a message.

Yet, when I tested it, this does not happen. A waiting task is not released from the message queue when calling rtems_message_queue_flush(). Moreover, I did not find any sign in the source code of rtems_message_queue_flush() which look liked it would dequeue waiting threads. (In contrast rtems_message_queue_delete() does!) Furthermore, there is no other hint in the documentation of either function that flush() would kick out waiting receivers.

I may misinterpret the documentation above or oversee something in the code. Yet, I believe the text I cited above is a mistake in the documentation and should simply be removed.

How to reproduce/How I tested:

# I created a message queue and a second task with a higher priority than the first one.
# I made the second task wait on the message empty queue by calling rtems_message_queue_receive().
# Mean while the first task called rtems_message_queue_flush() on the empty queue.
# Result: The second task does still wait on the queue after rtems_message_queue_flush() returned. It does not return with RTEMS_UNSATISFIED.

The debug output of my test looks like (the worker task is not released by rtems_message_queue_flush() but afterwards by a timeout of 3 ticks):

P:574:0:UI1/Valid/Valid/Valid/Flushed/Local/Fifo/Timeout/Empty/Nop:tc-message-re
ceive.c:1316
L:#### rtems_message_queue_construct() with
L:####   .maximum_pending_messages = 3
L:####   .maximum_message_size = 5
L:####   .storage_size = 72
L:####   .storage_free = 0
L:####   .attributes = 0 (LOCAL=0, FIFO=0, PRIORITY=4)
L:#### rtems_task_restart BEFORE
L:#### rtems_message_queue_receive(option_set=0, timeout_param=3 ) BEGIN
L:#### rtems_task_restart AFTER
L:#### rtems_message_queue_flush() BEFORE
L:#### rtems_message_queue_flush() AFTER
L:#### WaitForWorker wait ticks BEFORE
L:#### rtems_message_queue_receive() END status = 6 (0=RTEMS_SUCCESSFUL, 13=RTEMS_UNSATISFIED, 6=RTEMS_TIMEOUT )
L:#### WorkerTask send event
L:#### WaitForWorker wait ticks AFTER
F:586:0:UI1/Valid/Valid/Valid/Flushed/Local/Fifo/Timeout/Empty/Nop:tc-message-receive.c:1004:RTEMS_TIMEOUT == RTEMS_UNSATISFIED
F:587:0:UI1/Valid/Valid/Valid/Flushed/Local/Fifo/Timeout/Empty/Nop:tc-message-receive.c:1043:3 == 0
L:#### rtems_message_queue_delete()

For the records:

RTEMS_VERSION = 6.0.0
remote origin = git://git.rtems.org/sebh/rtems.git /* The HASH is also in git://git.rtems.org/rtems.git */
commit HEAD = bb77a82f619752ba147c317d982ac47f56f4afec
config.ini =

[arm/realview_pbx_a9_qemu]
RTEMS_DEBUG = True
RTEMS_NETWORKING = True
RTEMS_POSIX_API = True
RTEMS_SMP = True
BUILD_TESTS = True

NEWLIB_VERSION = 3.2.0
SOURCE_BUILDER = Set Builder, 6 (f12dee02d52d)
GCC_VERSION = arm-rtems6-gcc (GCC) 10.3.1 20210409 (RTEMS 6, RSB c938bd7cbe16bd03d3b382f2d7cfee6a86aa9424, Newlib 0c0f3df)
BINUTILS_VERSION = GNU ld (GNU Binutils) 2.36.1.20210409

Change History (3)

comment:1 Changed on Sep 14, 2021 at 3:19:16 PM by Frank Kuehndel

Keywords: qualification added

comment:2 Changed on Sep 16, 2021 at 7:34:37 AM by Sebastian Huber <sebastian.huber@…>

In dbb7c956/rtems:

rtems: Fix message manager documentation

Correct the description of the count parameter of
rtems_message_queue_flush().

Update #4508.

comment:3 Changed on Sep 16, 2021 at 7:37:35 AM by Sebastian Huber <sebastian.huber@…>

Resolution: fixed
Status: assignedclosed

In 7afc7a0/rtems-docs:

rtems: Fix message manager documentation

Correct the description of the count parameter of
rtems_message_queue_flush().

Close #4508.

Note: See TracTickets for help on using tickets.