Add a general way to request an immediate top-level callback.

This is a little like schedule_timer, in that the callback you provide
will be run from the top-level message loop of whatever application
you're in; but unlike the timer mechanism, it will happen
_immediately_.

The aim is to provide a general way to avoid re-entrance of code, in
cases where just _doing_ the thing you want done is liable to trigger
a confusing recursive call to the function in which you came to the
decision to do it; instead, you just request a top-level callback at
the message loop's earliest convenience, and do it then.

[originally from svn r10019]

callback.c

@@ -0,0 +1,68 @@
+/*
+ * Facility for queueing callback functions to be run from the
+ * top-level event loop after the current top-level activity finishes.
+ */
+
+#include <stddef.h>
+
+#include "putty.h"
+
+struct callback {
+    struct callback *next;
+
+    toplevel_callback_fn_t fn;
+    void *ctx;
+};
+
+struct callback *cbhead = NULL, *cbtail = NULL;
+
+toplevel_callback_notify_fn_t notify_frontend = NULL;
+void *frontend = NULL;
+
+void request_callback_notifications(toplevel_callback_notify_fn_t fn,
+                                    void *fr)
+{
+    notify_frontend = fn;
+    frontend = fr;
+}
+
+void queue_toplevel_callback(toplevel_callback_fn_t fn, void *ctx)
+{
+    struct callback *cb;
+
+    cb = snew(struct callback);
+    cb->fn = fn;
+    cb->ctx = ctx;
+
+    /* If the front end has requested notification of pending
+     * callbacks, and we didn't already have one queued, let it know
+     * we do have one now. */
+    if (notify_frontend && !cbhead)
+        notify_frontend(frontend);
+
+    if (cbtail)
+        cbtail->next = cb;
+    else
+        cbhead = cb;
+    cbtail = cb;
+    cb->next = NULL;
+}
+
+void run_toplevel_callbacks(void)
+{
+    while (cbhead) {
+        struct callback *cb = cbhead;
+        /*
+         * Careful ordering here. We call the function _before_
+         * advancing cbhead (though, of course, we must free cb
+         * _after_ advancing it). This means that if the very last
+         * callback schedules another callback, cbhead does not become
+         * NULL at any point in this while loop, and so the frontend
+         * notification function won't be needlessly pestered.
+         */
+        cb->fn(cb->ctx);
+        cbhead = cb->next;
+        sfree(cb);
+    }
+    cbtail = NULL;
+}