libpulp: introduce mailbox concept

The sleep functions, which are few, and the only current means for
fibers to block/enter the scheduler, now take an optional
pulp_mailbox_t * parameter.

When supplied, other fibers may communicate with the sleeping fiber
via pulp_fiber_get_mailslot().  This function checks the destination
fiber for a mailbox and verifies there's space available.  On success,
it returns a pointer to the next available mailslot while advancing
the mailboxes mail count.

The caller may then use this mailslot pointer to write directly to the
void * it references in the mailbox.  If the receiving fiber took care
to populate its mailbox with slots referencing external memory, the
sender could dereference the mailslot's value to find the external
memory and write larger messages without needing to allocate new space
itself only for the reciever to have to free it shortly.

It's also possible to not do anything at all with the mailslot.  Simply
successfully getting a mailslot communicates _something_ to the
recipient by virtue of the count advancing.

The returned mailslot can only be considered valid by the calling
fiber until it sleeps, after that the slot must be treated as
reclaimed from the perspective of the fiber that called
pulp_fiber_get_mailslot().

When the sleeping fiber wakes and returns from its mailbox-enabled
sleep call, it simply looks at the count member of the mailbox to see
if any mail was received.  It's up to the implementation what is done
with the contents of the mailbox.

The mailbox count is always reset to 0 automatically at the start of a
mailbox-enabled sleep.

1 files changed, 9 insertions, 2 deletions

diff --git a/src/pulp.h b/src/pulp.h
index 6111c80..c7edd0f 100644
--- a/src/pulp.h
+++ b/src/pulp.h
@@ -24,14 +24,21 @@ typedef struct pulp_t pulp_t;
 typedef uint64_t pulp_usec_t;
 typedef struct thunk_t thunk_t;
 
+/* for conveniences like trivial stack allocation, this is public */
+typedef struct pulp_mailbox_t {
+	unsigned	size, count;
+	void		*slots[];
+} pulp_mailbox_t;
+
 pulp_t * pulp_new(void);
 void pulp_free(pulp_t *pulp);
 int pulp_tick(pulp_t *pulp, unsigned *next_tick_delay_us);
 void pulp_run(pulp_t *pulp);
 pulp_fiber_t * pulp_fiber_new(pulp_t *pulp, unsigned delay_ms, thunk_t *thunk);
-void pulp_msleep(pulp_t *pulp, unsigned milliseconds);
-void pulp_sleep(pulp_t *pulp, unsigned seconds);
+void pulp_msleep(pulp_t *pulp, unsigned milliseconds, pulp_mailbox_t *mailbox);
+void pulp_sleep(pulp_t *pulp, unsigned seconds, pulp_mailbox_t *mailbox);
 pulp_usec_t pulp_now(pulp_t *pulp);
 pulp_fiber_t * pulp_self(pulp_t *pulp);
+int pulp_fiber_get_mailslot(pulp_t *pulp, pulp_fiber_t *fiber, void ***res_mailslot);
 
 #endif