Merge pull request atomvm#602 from bettio/add-take-message-function

Add mailbox_take_message function

Return the message without disposing it. This can be useful for having full control on received messages.

These changes are made under both the "Apache 2.0" and the "GNU Lesser General
Public License 2.1 or later" license terms (dual license).

SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later

Author: bettio

src/libAtomVM/mailbox.c

@@ -367,14 +367,14 @@ bool mailbox_peek(Context *c, term *out)
     return true;
 }
 
-void mailbox_remove_message(Mailbox *mbox, Heap *heap)
+MailboxMessage *mailbox_take_message(Mailbox *mbox)
 {
     // This is called from OP_REMOVE_MESSAGE opcode, so we cannot make any
     // assumption about the state and should perform a nop if the mailbox
     // is empty.
     if (UNLIKELY(mbox->receive_pointer == NULL)) {
         fprintf(stderr, "OP_REMOVE_MESSAGE on empty mailbox\n");
-        return;
+        return NULL;
     }
     MailboxMessage *removed = mbox->receive_pointer;
     if (mbox->receive_pointer_prev) {
@@ -393,9 +393,10 @@ void mailbox_remove_message(Mailbox *mbox, Heap *heap)
         }
     }
 
-    mailbox_message_dispose(removed, heap);
     // Reset receive pointers
     mailbox_reset(mbox);
+
+    return removed;
 }
 
 Message *mailbox_first(Mailbox *mbox)

src/libAtomVM/mailbox.h

@@ -38,6 +38,7 @@ extern "C" {
 #include "list.h"
 #include "smp.h"
 #include "term_typedef.h"
+#include "utils.h"
 
 struct Context;
 
@@ -264,14 +265,14 @@ static inline bool mailbox_has_next(Mailbox *mbox)
 bool mailbox_peek(Context *ctx, term *out);
 
 /**
- * @brief Remove next message from mailbox.
+ * @brief Take next message from mailbox.
  *
- * @details Discard a term that has been previously queued on a certain process
- * or driver mailbox. To be called from the process only. Term messages are
- * actually added as fragments to the heap and will be gone at next GC.
- * @param mbx the mailbox to remove next message from.
+ * @details Remove the first message from the mailbox and return it.
+ * To be called from the process only.
+ * This function is intended for some corner cases, such as certain port drivers.
+ * @param mbox the mailbox to take the next message from.
  */
-void mailbox_remove_message(Mailbox *mbox, Heap *ctx);
+MailboxMessage *mailbox_take_message(Mailbox *mbox);
 
 /**
  * @brief Get first message from mailbox.
@@ -304,6 +305,22 @@ void mailbox_destroy(Mailbox *mbox, Heap *heap);
  */
 void mailbox_message_dispose(MailboxMessage *m, Heap *heap);
 
+/**
+ * @brief Remove next message from mailbox.
+ *
+ * @details Discard a term that has been previously queued on a certain process
+ * or driver mailbox. To be called from the process only. Term messages are
+ * actually added as fragments to the heap and will be gone at next GC.
+ * @param mbx the mailbox to remove next message from.
+ */
+static inline void mailbox_remove_message(Mailbox *mbox, Heap *heap)
+{
+    MailboxMessage *removed = mailbox_take_message(mbox);
+    if (LIKELY(removed != NULL)) {
+        mailbox_message_dispose(removed, heap);
+    }
+}
+
 /**
  * @brief Output mailbox to stderr for crashdump reporting.
  *