mailbox: add function that remove and return message from mailbox

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

Signed-off-by: Davide Bettio <[email protected]>

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,18 @@ void mailbox_remove_message(Mailbox *mbox, Heap *heap)
         }
     }
 
-    mailbox_message_dispose(removed, heap);
     // Reset receive pointers
     mailbox_reset(mbox);
+
+    return removed;
+}
+
+void mailbox_remove_message(Mailbox *mbox, Heap *heap)
+{
+    MailboxMessage *removed = mailbox_take_message(mbox);
+    if (LIKELY(removed != NULL)) {
+        mailbox_message_dispose(removed, heap);
+    }
 }
 
 Message *mailbox_first(Mailbox *mbox)

src/libAtomVM/mailbox.h

@@ -263,6 +263,16 @@ static inline bool mailbox_has_next(Mailbox *mbox)
  */
 bool mailbox_peek(Context *ctx, term *out);
 
+/**
+ * @brief Take next message from mailbox.
+ *
+ * @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.
+ */
+MailboxMessage *mailbox_take_message(Mailbox *mbox);
+
 /**
  * @brief Remove next message from mailbox.
  *