Introduce new generic I/O event framework.

1 files changed, 109 insertions, 0 deletions

diff --git a/src/core/ioev.h b/src/core/ioev.h
new file mode 100644
index 00000000..e635e0c0
--- /dev/null
+++ b/src/core/ioev.h
@@ -0,0 +1,109 @@
+//
+// Copyright 2017 Garrett D'Amore <garrett@damore.org>
+//
+// This software is supplied under the terms of the MIT License, a
+// copy of which should be located in the distribution where this
+// file was obtained (LICENSE.txt).  A copy of the license may also be
+// found online at https://opensource.org/licenses/MIT.
+//
+
+#ifndef CORE_IOEV_H
+#define CORE_IOEV_H
+
+#include "core/defs.h"
+#include "core/thread.h"
+
+typedef struct nni_ioev_ops	nni_ioev_ops;
+typedef struct nni_ioev		nni_ioev;
+
+// Provider specific operations on I/O events.  We only have cancellation
+// at present.
+struct nni_ioev_ops {
+	// Cancel the I/O.  This should not callback up, but instead should
+	// just do whatever is necessary to free provider specific state,
+	// and unlink the I/O from any schedule.  The I/O itself will not
+	// have been started if this is called.
+	void (*ip_cancel)(void *);
+};
+
+// An nni_iov is an I/O event handle, used to represent asynchronous I/O.
+// These take several different forms.
+struct nni_ioev {
+	int		ie_result;      // Result code (nng_errno)
+	size_t		ie_count;       // Bytes transferred (I/O only)
+	nni_cb		ie_cb;          // User specified callback.
+	void *		ie_cbarg;       // Callback argument.
+
+	// These fields are private to the io events framework.
+	nni_mtx		ie_lk;
+	nni_cv		ie_cv;
+	unsigned	ie_flags;
+
+	// Provider data.
+	nni_ioev_ops	ie_prov_ops;
+	void *		ie_prov_data;
+};
+
+// nni_ioev_init initializes an IO event.  The callback is called with
+// the supplied argument when the operation is complete.  If NULL is
+// supplied for the callback, then nni_ioev_wake is used in its place,
+// and the ioev is used for the argument.
+extern void nni_ioev_init(nni_ioev *, nni_cb, void *);
+
+// nni_ioev_fini finalizes the IO event, releasing resources (locks)
+// associated with it.  The caller is responsible for ensuring that any
+// associated I/O is unscheduled or complete.
+extern void nni_ioev_fini(nni_ioev *);
+
+// nni_ioev_cancel cancels the IO event.  The result will be NNG_ECANCELED,
+// unless the underlying IO has already completed.
+extern void nni_ioev_cancel(nni_ioev *);
+
+// nni_ioev_result returns the result code (0 on success, or an NNG errno)
+// for the operation.  It is only valid to call this when the operation is
+// complete (such as when the callback is executed or after nni_ioev_wait
+// is performed).
+extern int nni_ioev_result(nni_ioev *);
+
+// nni_ioev_count returns the number of bytes of data transferred, if any.
+// As with nni_ioev_result, it is only defined if the I/O operation has
+// completed.
+extern size_t nni_ioev_count(nni_ioev *);
+
+// nni_ioev_wake wakes any threads blocked in nni_ioev_wait.  This is the
+// default callback if no other is supplied.  If a user callback is supplied
+// then that code must call this routine to wake any waiters (unless the
+// user code is certain that there are no such waiters).
+extern void nni_ioev_wake(nni_ioev *);
+
+// nni_ioev_wait blocks the caller until the IO event is complete, as indicated
+// by nni_ioev_wake being called.  (Recall nni_ioev_wake is the default
+// callback if none is supplied.)  If a user supplied callback is provided,
+// and that callback does not call nni_ioev_wake, then this routine may
+// block the caller indefinitely.
+extern void nni_ioev_wait(nni_ioev *);
+
+// I/O provider related functions.
+extern void nni_ioev_set_ops(nni_ioev *, nni_ioev_ops *, void *);
+
+// nni_ioev_busy is called by the provider to begin an operation, marking
+// the IO busy.  The framework will avoid calling back into the provider
+// (for cancellation for example) while the ioev is busy.  It is important
+// that the busy state be held for only brief periods of time, such as while
+// a non-blocking I/O operation is in progress.  If the IO is canceled (or
+// a cancellation is in progress), the function will return NNG_ECANCELED.
+// In this case, the provider must not perform any further I/O operations,
+// and must not call the completion routine.  Otherwise zero is returned.
+extern int nni_ioev_busy(nni_ioev *);
+
+// nni_ioev_unbusy clears the "busy" state set by nni_ioev_busy.
+extern void nni_ioev_unbusy(nni_ioev *);
+
+// nni_ioev_finish is called by the provider when an operation is complete.
+// (This can be for any reason other than cancellation.)  The provider gives
+// the result code (0 for success, an NNG errno otherwise), and the amount of
+// data transferred (if any).  The ioev must have been marked busy when this
+// is called.  The ioev busy state is automatically cleared by this routine.
+extern void nni_ioev_finish(nni_ioev *, int, size_t);
+
+#endif // CORE_IOEV_H