Document new sys_arch_mbox_tryfetch requirement for ports

diff --git a/doc/sys_arch.txt b/doc/sys_arch.txt
index b2c45e03ef27cb4aab73121e375ff6888e00a1b6..b6103ac3cc8b2c9d959f4bfff4a812b89e99da47 100644 (file)
--- a/doc/sys_arch.txt
+++ b/doc/sys_arch.txt
@@ -98,6 +98,19 @@ The following functions must be implemented by the sys_arch:
 
   Note that a function with a similar name, sys_mbox_fetch(), is
   implemented by lwIP. 
+
+- u32_t sys_arch_mbox_tryfetch(sys_mbox_t mbox, void **msg)
+
+  This is similar to sys_arch_mbox_fetch, however if a message is not
+  present in the mailbox, it immediately returns with the code
+  SYS_MBOX_EMPTY.
+
+  To allow for efficient implementations, this can be defined as a
+  function-like macro in sys_arch.h instead of a normal function. For
+  example, a naive implementation could be:
+    #define sys_arch_mbox_tryfetch(mbox,msg) \
+      sys_arch_mbox_fetch(mbox,msg,1)
+  although this would introduce unnecessary delays.
   
 - struct sys_timeouts *sys_arch_timeouts(void)