source: libcfa/src/concurrency/io.cfa @ df2e00f

//
// Cforall Version 1.0.0 Copyright (C) 2020 University of Waterloo
//
// The contents of this file are covered under the licence agreement in the
// file "LICENCE" distributed with Cforall.
//
// io.cfa --
//
// Author           : Thierry Delisle
// Created On       : Thu Apr 23 17:31:00 2020
// Last Modified By :
// Last Modified On :
// Update Count     :
//

#define __cforall_thread__

#if defined(__CFA_DEBUG__)
        // #define __CFA_DEBUG_PRINT_IO__
        // #define __CFA_DEBUG_PRINT_IO_CORE__
#endif


#if defined(CFA_HAVE_LINUX_IO_URING_H)
        #include <errno.h>
        #include <signal.h>
        #include <stdint.h>
        #include <string.h>
        #include <unistd.h>

        extern "C" {
                #include <sys/syscall.h>
                #include <sys/eventfd.h>
                #include <sys/uio.h>

                #include <linux/io_uring.h>
        }

        #include "stats.hfa"
        #include "kernel.hfa"
        #include "kernel/fwd.hfa"
        #include "kernel/private.hfa"
        #include "kernel/cluster.hfa"
        #include "io/types.hfa"

        __attribute__((unused)) static const char * opcodes[] = {
                "OP_NOP",
                "OP_READV",
                "OP_WRITEV",
                "OP_FSYNC",
                "OP_READ_FIXED",
                "OP_WRITE_FIXED",
                "OP_POLL_ADD",
                "OP_POLL_REMOVE",
                "OP_SYNC_FILE_RANGE",
                "OP_SENDMSG",
                "OP_RECVMSG",
                "OP_TIMEOUT",
                "OP_TIMEOUT_REMOVE",
                "OP_ACCEPT",
                "OP_ASYNC_CANCEL",
                "OP_LINK_TIMEOUT",
                "OP_CONNECT",
                "OP_FALLOCATE",
                "OP_OPENAT",
                "OP_CLOSE",
                "OP_FILES_UPDATE",
                "OP_STATX",
                "OP_READ",
                "OP_WRITE",
                "OP_FADVISE",
                "OP_MADVISE",
                "OP_SEND",
                "OP_RECV",
                "OP_OPENAT2",
                "OP_EPOLL_CTL",
                "OP_SPLICE",
                "OP_PROVIDE_BUFFERS",
                "OP_REMOVE_BUFFERS",
                "OP_TEE",
                "INVALID_OP"
        };

        static io_context$ * __ioarbiter_allocate( io_arbiter$ & this, __u32 idxs[], __u32 want );
        static void __ioarbiter_submit( io_context$ * , __u32 idxs[], __u32 have, bool lazy );
        static void __ioarbiter_flush ( io_context$ &, bool kernel );
        static inline void __ioarbiter_notify( io_context$ & ctx );
//=============================================================================================
// I/O Polling
//=============================================================================================
        static inline unsigned __flush( struct io_context$ & );
        static inline __u32 __release_sqes( struct io_context$ & );
        extern void __kernel_unpark( thread$ * thrd, unpark_hint );

        static inline void __post(oneshot & this, bool kernel, unpark_hint hint) {
                thread$ * t = post( this, false );
                if(kernel) __kernel_unpark( t, hint );
                else unpark( t, hint );
        }

        // actual system call of io uring
        // wrap so everything that needs to happen around it is always done
        //   i.e., stats, book keeping, sqe reclamation, etc.
        static void ioring_syscsll( struct io_context$ & ctx, unsigned int min_comp, unsigned int flags ) {
                __STATS__( true, io.calls.flush++; )
                int ret;
                for() {
                        // do the system call in a loop, repeat on interrupts
                        ret = syscall( __NR_io_uring_enter, ctx.fd, ctx.sq.to_submit, min_comp, flags, (sigset_t *)0p, _NSIG / 8);
                        if( ret < 0 ) {
                                switch((int)errno) {
                                case EINTR:
                                        continue;
                                case EAGAIN:
                                case EBUSY:
                                        // Update statistics
                                        __STATS__( false, io.calls.errors.busy ++; )
                                        return false;
                                default:
                                        abort( "KERNEL ERROR: IO_URING SYSCALL - (%d) %s\n", (int)errno, strerror(errno) );
                                }
                        }
                        break;
                }

                __cfadbg_print_safe(io, "Kernel I/O : %u submitted to io_uring %d\n", ret, ctx.fd);
                __STATS__( true, io.calls.submitted += ret; )
                /* paranoid */ verify( ctx.sq.to_submit <= *ctx.sq.num );
                /* paranoid */ verify( ctx.sq.to_submit >= ret );

                // keep track of how many still need submitting
                __atomic_fetch_sub(&ctx.sq.to_submit, ret, __ATOMIC_SEQ_CST);

                /* paranoid */ verify( ctx.sq.to_submit <= *ctx.sq.num );

                // Release the consumed SQEs
                __release_sqes( ctx );

                /* paranoid */ verify( ! __preemption_enabled() );

                // mark that there is no pending io left
                __atomic_store_n(&ctx.proc->io.pending, false, __ATOMIC_RELAXED);
        }

        // try to acquire an io context for draining, helping means we never *need* to drain, we can always do it later
        static bool try_acquire( io_context$ * ctx ) __attribute__((nonnull(1))) {
                /* paranoid */ verify( ! __preemption_enabled() );
                /* paranoid */ verify( ready_schedule_islocked() );


                {
                        // if there is nothing to drain there is no point in acquiring anything
                        const __u32 head = *ctx->cq.head;
                        const __u32 tail = *ctx->cq.tail;

                        if(head == tail) return false;
                }

                // try a simple spinlock acquire, it's likely there are completions to drain
                if(!__atomic_try_acquire(&ctx->cq.try_lock)) {
                        // some other processor already has it
                        __STATS__( false, io.calls.locked++; )
                        return false;
                }

                // acquired!!
                return true;
        }

        // actually drain the completion
        static bool __cfa_do_drain( io_context$ * ctx, cluster * cltr ) __attribute__((nonnull(1, 2))) {
                /* paranoid */ verify( ! __preemption_enabled() );
                /* paranoid */ verify( ready_schedule_islocked() );
                /* paranoid */ verify( ctx->cq.try_lock == true );

                // get all the invariants and initial state
                const __u32 mask = *ctx->cq.mask;
                const __u32 num  = *ctx->cq.num;
                unsigned long long ts_prev = ctx->cq.ts;
                unsigned long long ts_next;

                // We might need to do this multiple times if more events completed than can fit in the queue.
                for() {
                        // re-read the head and tail in case it already changed.
                        // count the difference between the two
                        const __u32 head = *ctx->cq.head;
                        const __u32 tail = *ctx->cq.tail;
                        const __u32 count = tail - head;
                        __STATS__( false, io.calls.drain++; io.calls.completed += count; )

                        // for everything between head and tail, drain it
                        for(i; count) {
                                unsigned idx = (head + i) & mask;
                                volatile struct io_uring_cqe & cqe = ctx->cq.cqes[idx];

                                /* paranoid */ verify(&cqe);

                                // find the future in the completion
                                struct io_future_t * future = (struct io_future_t *)(uintptr_t)cqe.user_data;
                                // __cfadbg_print_safe( io, "Kernel I/O : Syscall completed : cqe %p, result %d for %p\n", &cqe, cqe.res, future );

                                // don't directly fulfill the future, preemption is disabled so we need to use kernel_unpark
                                __kernel_unpark( fulfil( *future, cqe.res, false ), UNPARK_LOCAL );
                        }

                        // update the timestamps accordingly
                        // keep a local copy so we can update the relaxed copy
                        ts_next = ctx->cq.ts = rdtscl();

                        // Mark to the kernel that the cqe has been seen
                        // Ensure that the kernel only sees the new value of the head index after the CQEs have been read.
                        __atomic_store_n( ctx->cq.head, head + count, __ATOMIC_SEQ_CST );
                        ctx->proc->idle_wctx.drain_time = ts_next;

                        // we finished draining the completions... unless the ring buffer was full and there are more secret completions in the kernel.
                        if(likely(count < num)) break;

                        // the ring buffer was full, there could be more stuff in the kernel.
                        ioring_syscsll( *ctx, 0, IORING_ENTER_GETEVENTS);
                }

                __cfadbg_print_safe(io, "Kernel I/O : %u completed age %llu\n", count, ts_next);
                /* paranoid */ verify( ready_schedule_islocked() );
                /* paranoid */ verify( ! __preemption_enabled() );

                // everything is drained, we can release the lock
                __atomic_unlock(&ctx->cq.try_lock);

                // update the relaxed timestamp
                touch_tsc( cltr->sched.io.tscs, ctx->cq.id, ts_prev, ts_next, false );

                return true;
        }

        // call from a processor to flush
        // contains all the bookkeeping a proc must do, not just the barebones flushing logic
        void __cfa_do_flush( io_context$ & ctx, bool kernel ) {
                /* paranoid */ verify( ! __preemption_enabled() );

                // flush any external requests
                ctx.sq.last_external = false; // clear the external bit, the arbiter will reset it if needed
                __ioarbiter_flush( ctx, kernel );

                // if submitting must be submitted, do the system call
                if(ctx.sq.to_submit != 0) {
                        ioring_syscsll(ctx, 0, 0);
                }
        }

        // call from a processor to drain
        // contains all the bookkeeping a proc must do, not just the barebones draining logic
        bool __cfa_io_drain( struct processor * proc ) {
                bool local = false;
                bool remote = false;

                // make sure no ones creates/destroys io contexts
                ready_schedule_lock();

                cluster * const cltr = proc->cltr;
                io_context$ * const ctx = proc->io.ctx;
                /* paranoid */ verify( cltr );
                /* paranoid */ verify( ctx );

                // Help if needed
                with(cltr->sched) {
                        const size_t ctxs_count = io.count;

                        /* paranoid */ verify( ready_schedule_islocked() );
                        /* paranoid */ verify( ! __preemption_enabled() );
                        /* paranoid */ verify( active_processor() == proc );
                        /* paranoid */ verify( __shard_factor.io > 0 );
                        /* paranoid */ verify( ctxs_count > 0 );
                        /* paranoid */ verify( ctx->cq.id < ctxs_count );

                        const unsigned this_cache = cache_id(cltr, ctx->cq.id / __shard_factor.io);
                        const unsigned long long ctsc = rdtscl();

                        // only help once every other time
                        // pick a target when not helping
                        if(proc->io.target == UINT_MAX) {
                                uint64_t chaos = __tls_rand();
                                // choose who to help and whether to accept helping far processors 
                                unsigned ext = chaos & 0xff;
                                unsigned other  = (chaos >> 8) % (ctxs_count);

                                // if the processor is on the same cache line or is lucky ( 3 out of 256 odds ) help it
                                if(ext < 3 || __atomic_load_n(&caches[other / __shard_factor.io].id, __ATOMIC_RELAXED) == this_cache) {
                                        proc->io.target = other;
                                }
                        }
                        else {
                                // a target was picked last time, help it
                                const unsigned target = proc->io.target;
                                /* paranoid */ verify( io.tscs[target].t.tv != ULLONG_MAX );
                                // make sure the target hasn't stopped existing since last time
                                HELP: if(target < ctxs_count) {
                                        // calculate it's age and how young it could be before we give up on helping
                                        const __readyQ_avg_t cutoff = calc_cutoff(ctsc, ctx->cq.id, ctxs_count, io.data, io.tscs, __shard_factor.io, false);
                                        const __readyQ_avg_t age = moving_average(ctsc, io.tscs[target].t.tv, io.tscs[target].t.ma, false);
                                        __cfadbg_print_safe(io, "Kernel I/O: Help attempt on %u from %u, age %'llu vs cutoff %'llu, %s\n", target, ctx->cq.id, age, cutoff, age > cutoff ? "yes" : "no");
                                        // is the target older than the cutoff, recall 0 is oldest and bigger ints are younger
                                        if(age <= cutoff) break HELP;

                                        // attempt to help the submission side
                                        __cfa_do_flush( *io.data[target], true );

                                        // attempt to help the completion side
                                        if(!try_acquire(io.data[target])) break HELP; // already acquire no help needed

                                        // actually help
                                        if(!__cfa_do_drain( io.data[target], cltr )) break HELP;

                                        // track we did help someone
                                        remote = true;
                                        __STATS__( true, io.calls.helped++; )
                                }

                                // reset the target
                                proc->io.target = UINT_MAX;
                        }
                }

                // Drain the local queue
                if(try_acquire( proc->io.ctx )) {
                        local = __cfa_do_drain( proc->io.ctx, cltr );
                }

                /* paranoid */ verify( ready_schedule_islocked() );
                /* paranoid */ verify( ! __preemption_enabled() );
                /* paranoid */ verify( active_processor() == proc );

                ready_schedule_unlock();

                // return true if some completion entry, local or remote, was drained
                return local || remote;
        }



        // call from a processor to flush
        // contains all the bookkeeping a proc must do, not just the barebones flushing logic
        bool __cfa_io_flush( struct processor * proc ) {
                /* paranoid */ verify( ! __preemption_enabled() );
                /* paranoid */ verify( proc );
                /* paranoid */ verify( proc->io.ctx );

                __cfa_do_flush( *proc->io.ctx, false );

                // also drain since some stuff will immediately complete
                return __cfa_io_drain( proc );
        }

//=============================================================================================
// I/O Submissions
//=============================================================================================

// Submition steps :
// 1 - Allocate a queue entry. The ring already has memory for all entries but only the ones
//     listed in sq.array are visible by the kernel. For those not listed, the kernel does not
//     offer any assurance that an entry is not being filled by multiple flags. Therefore, we
//     need to write an allocator that allows allocating concurrently.
//
// 2 - Actually fill the submit entry, this is the only simple and straightforward step.
//
// 3 - Append the entry index to the array and adjust the tail accordingly. This operation
//     needs to arrive to two concensus at the same time:
//     A - The order in which entries are listed in the array: no two threads must pick the
//         same index for their entries
//     B - When can the tail be update for the kernel. EVERY entries in the array between
//         head and tail must be fully filled and shouldn't ever be touched again.
//
        //=============================================================================================
        // Allocation
        // for user's convenience fill the sqes from the indexes
        static inline void __fill(struct io_uring_sqe * out_sqes[], __u32 want, __u32 idxs[], struct io_context$ * ctx)  {
                struct io_uring_sqe * sqes = ctx->sq.sqes;
                for(i; want) {
                        // __cfadbg_print_safe(io, "Kernel I/O : filling loop\n");
                        out_sqes[i] = &sqes[idxs[i]];
                }
        }

        // Try to directly allocate from the a given context
        // Not thread-safe
        static inline bool __alloc(struct io_context$ * ctx, __u32 idxs[], __u32 want) {
                __sub_ring_t & sq = ctx->sq;
                const __u32 mask  = *sq.mask;
                __u32 fhead = sq.free_ring.head;    // get the current head of the queue
                __u32 ftail = sq.free_ring.tail;    // get the current tail of the queue

                // If we don't have enough sqes, fail
                if((ftail - fhead) < want) { return false; }

                // copy all the indexes we want from the available list
                for(i; want) {
                        // __cfadbg_print_safe(io, "Kernel I/O : allocating loop\n");
                        idxs[i] = sq.free_ring.array[(fhead + i) & mask];
                }

                // Advance the head to mark the indexes as consumed
                __atomic_store_n(&sq.free_ring.head, fhead + want, __ATOMIC_RELEASE);

                // return success
                return true;
        }

        // Allocate an submit queue entry.
        // The kernel cannot see these entries until they are submitted, but other threads must be
        // able to see which entries can be used and which are already un used by an other thread
        // for convenience, return both the index and the pointer to the sqe
        // sqe == &sqes[idx]
        struct io_context$ * cfa_io_allocate(struct io_uring_sqe * sqes[], __u32 idxs[], __u32 want) libcfa_public {
                // __cfadbg_print_safe(io, "Kernel I/O : attempting to allocate %u\n", want);

                disable_interrupts();
                struct processor * proc = __cfaabi_tls.this_processor;
                io_context$ * ctx = proc->io.ctx;
                /* paranoid */ verify( __cfaabi_tls.this_processor );
                /* paranoid */ verify( ctx );

                // __cfadbg_print_safe(io, "Kernel I/O : attempting to fast allocation\n");

                // We can proceed to the fast path
                if( __alloc(ctx, idxs, want) ) {
                        // Allocation was successful
                        __STATS__( true, io.alloc.fast += 1; )
                        enable_interrupts();

                        // __cfadbg_print_safe(io, "Kernel I/O : fast allocation successful from ring %d\n", ctx->fd);

                        __fill( sqes, want, idxs, ctx );
                        return ctx;
                }
                // The fast path failed, fallback
                __STATS__( true, io.alloc.fail += 1; )

                // Fast path failed, fallback on arbitration
                __STATS__( true, io.alloc.slow += 1; )
                enable_interrupts();

                io_arbiter$ * ioarb = proc->cltr->io.arbiter;
                /* paranoid */ verify( ioarb );

                // __cfadbg_print_safe(io, "Kernel I/O : falling back on arbiter for allocation\n");

                struct io_context$ * ret = __ioarbiter_allocate(*ioarb, idxs, want);

                // __cfadbg_print_safe(io, "Kernel I/O : slow allocation completed from ring %d\n", ret->fd);

                __fill( sqes, want, idxs,ret );
                return ret;
        }

        //=============================================================================================
        // submission
        // barebones logic to submit a group of sqes
        static inline void __submit_only( struct io_context$ * ctx, __u32 idxs[], __u32 have, bool lock) {
                if(!lock) 
                        lock( ctx->ext_sq.lock __cfaabi_dbg_ctx2 );
                // We can proceed to the fast path
                // Get the right objects
                __sub_ring_t & sq = ctx->sq;
                const __u32 mask  = *sq.mask;
                __u32 tail = *sq.kring.tail;

                // Add the sqes to the array
                for( i; have ) {
                        // __cfadbg_print_safe(io, "Kernel I/O : __submit loop\n");
                        sq.kring.array[ (tail + i) & mask ] = idxs[i];
                }

                // Make the sqes visible to the submitter
                __atomic_store_n(sq.kring.tail, tail + have, __ATOMIC_RELEASE);
                __atomic_fetch_add(&sq.to_submit, have, __ATOMIC_SEQ_CST);

                // set the bit to mark things need to be flushed
                __atomic_store_n(&ctx->proc->io.pending, true, __ATOMIC_RELAXED);
                __atomic_store_n(&ctx->proc->io.dirty  , true, __ATOMIC_RELAXED);

                if(!lock) 
                        unlock( ctx->ext_sq.lock );
        }

        // submission logic + maybe flushing
        static inline void __submit( struct io_context$ * ctx, __u32 idxs[], __u32 have, bool lazy) {
                __sub_ring_t & sq = ctx->sq;
                __submit_only(ctx, idxs, have, false);

                if(sq.to_submit > 30) {
                        __tls_stats()->io.flush.full++;
                        __cfa_io_flush( ctx->proc );
                }
                if(!lazy) {
                        __tls_stats()->io.flush.eager++;
                        __cfa_io_flush( ctx->proc );
                }
        }

        // call from a processor to flush
        // might require arbitration if the thread was migrated after the allocation
        void cfa_io_submit( struct io_context$ * inctx, __u32 idxs[], __u32 have, bool lazy ) __attribute__((nonnull (1))) libcfa_public {
                // __cfadbg_print_safe(io, "Kernel I/O : attempting to submit %u (%s)\n", have, lazy ? "lazy" : "eager");

                disable_interrupts();
                __STATS__( true, if(!lazy) io.submit.eagr += 1; )
                struct processor * proc = __cfaabi_tls.this_processor;
                io_context$ * ctx = proc->io.ctx;
                /* paranoid */ verify( __cfaabi_tls.this_processor );
                /* paranoid */ verify( ctx );

                // Can we proceed to the fast path
                if( ctx == inctx )              // We have the right instance?
                {
                        // yes! fast submit
                        __submit(ctx, idxs, have, lazy);

                        // Mark the instance as no longer in-use, re-enable interrupts and return
                        __STATS__( true, io.submit.fast += 1; )
                        enable_interrupts();

                        // __cfadbg_print_safe(io, "Kernel I/O : submitted on fast path\n");
                        return;
                }

                // Fast path failed, fallback on arbitration
                __STATS__( true, io.submit.slow += 1; )
                enable_interrupts();

                // __cfadbg_print_safe(io, "Kernel I/O : falling back on arbiter for submission\n");

                __ioarbiter_submit(inctx, idxs, have, lazy);
        }

        //=============================================================================================
        // Flushing
        // Go through the ring's submit queue and release everything that has already been consumed
        // by io_uring
        // This cannot be done by multiple threads
        static __u32 __release_sqes( struct io_context$ & ctx ) {
                const __u32 mask = *ctx.sq.mask;

                __attribute__((unused))
                __u32 ctail = *ctx.sq.kring.tail;    // get the current tail of the queue
                __u32 chead = *ctx.sq.kring.head;        // get the current head of the queue
                __u32 phead = ctx.sq.kring.released; // get the head the last time we were here

                __u32 ftail = ctx.sq.free_ring.tail;  // get the current tail of the queue

                // the 3 fields are organized like this diagram
                // except it's are ring
                // ---+--------+--------+----
                // ---+--------+--------+----
                //    ^        ^        ^
                // phead    chead    ctail

                // make sure ctail doesn't wrap around and reach phead
                /* paranoid */ verify(
                           (ctail >= chead && chead >= phead)
                        || (chead >= phead && phead >= ctail)
                        || (phead >= ctail && ctail >= chead)
                );

                // find the range we need to clear
                __u32 count = chead - phead;

                if(count == 0) {
                        return 0;
                }

                // We acquired an previous-head/current-head range
                // go through the range and release the sqes
                for( i; count ) {
                        // __cfadbg_print_safe(io, "Kernel I/O : release loop\n");
                        __u32 idx = ctx.sq.kring.array[ (phead + i) & mask ];
                        ctx.sq.free_ring.array[ (ftail + i) & mask ] = idx;
                }

                ctx.sq.kring.released = chead;          // note up to were we processed
                __atomic_store_n(&ctx.sq.free_ring.tail, ftail + count, __ATOMIC_SEQ_CST);

                // notify the allocator that new allocations can be made
                __ioarbiter_notify(ctx);

                return count;
        }

//=============================================================================================
// I/O Arbiter
//=============================================================================================
        static inline bool enqueue(__outstanding_io_queue & queue, __outstanding_io & item) {
                bool was_empty;

                // Lock the list, it's not thread safe
                lock( queue.lock __cfaabi_dbg_ctx2 );
                {
                        was_empty = queue.queue`isEmpty;

                        // Add our request to the list
                        insert_last( queue.queue, item );

                        // Mark as pending
                        __atomic_store_n( &queue.empty, false, __ATOMIC_SEQ_CST );
                }
                unlock( queue.lock );

                return was_empty;
        }

        static inline bool empty(__outstanding_io_queue & queue ) {
                return __atomic_load_n( &queue.empty, __ATOMIC_SEQ_CST);
        }

        static io_context$ * __ioarbiter_allocate( io_arbiter$ & this, __u32 idxs[], __u32 want ) {
                // __cfadbg_print_safe(io, "Kernel I/O : arbiter allocating\n");

                __STATS__( false, io.alloc.block += 1; )

                // No one has any resources left, wait for something to finish
                // We need to add ourself to a list of pending allocs and wait for an answer
                __pending_alloc pa;
                pa.idxs = idxs;
                pa.want = want;

                enqueue(this.pending, (__outstanding_io&)pa);

                wait( pa.waitctx );

                return pa.ctx;

        }

        // notify the arbiter that new allocations are available
        static void __ioarbiter_notify( io_arbiter$ & this, io_context$ * ctx ) {
                /* paranoid */ verify( !this.pending.queue`isEmpty );
                /* paranoid */ verify( __preemption_enabled() );

                // mutual exclusion is needed
                lock( this.pending.lock __cfaabi_dbg_ctx2 );
                {
                        __cfadbg_print_safe(io, "Kernel I/O : notifying\n");

                        // as long as there are pending allocations try to satisfy them
                        // for simplicity do it in FIFO order
                        while( !this.pending.queue`isEmpty ) {
                                // get first pending allocs
                                __u32 have = ctx->sq.free_ring.tail - ctx->sq.free_ring.head;
                                __pending_alloc & pa = (__pending_alloc&)(this.pending.queue`first);

                                // check if we have enough to satisfy the request
                                if( have > pa.want ) goto DONE;

                                // if there are enough allocations it means we can drop the request
                                try_pop_front( this.pending.queue );

                                /* paranoid */__attribute__((unused)) bool ret =

                                // actually do the alloc
                                __alloc(ctx, pa.idxs, pa.want);

                                /* paranoid */ verify( ret );

                                // write out which context statisfied the request and post
                                // this 
                                pa.ctx = ctx;
                                post( pa.waitctx );
                        }

                        this.pending.empty = true;
                        DONE:;
                }
                unlock( this.pending.lock );

                /* paranoid */ verify( __preemption_enabled() );
        }

        // short hand to avoid the mutual exclusion of the pending is empty regardless
        static void __ioarbiter_notify( io_context$ & ctx ) {
                if(empty( ctx.arbiter->pending )) return;
                __ioarbiter_notify( *ctx.arbiter, &ctx );
        }

        // Submit from outside the local processor: append to the outstanding list
        static void __ioarbiter_submit( io_context$ * ctx, __u32 idxs[], __u32 have, bool lazy ) {
                __cfadbg_print_safe(io, "Kernel I/O : submitting %u from the arbiter to context %u\n", have, ctx->fd);

                __cfadbg_print_safe(io, "Kernel I/O : waiting to submit %u\n", have);

                // create the intrusive object to append
                __external_io ei;
                ei.idxs = idxs;
                ei.have = have;
                ei.lazy = lazy;

                // enqueue the io
                bool we = enqueue(ctx->ext_sq, (__outstanding_io&)ei);

                // mark pending
                __atomic_store_n(&ctx->proc->io.pending, true, __ATOMIC_SEQ_CST);

                // if this is the first to be enqueued, signal the processor in an attempt to speed up flushing
                // if it's not the first enqueue, a signal is already in transit
                if( we ) {
                        sigval_t value = { PREEMPT_IO };
                        __cfaabi_pthread_sigqueue(ctx->proc->kernel_thread, SIGUSR1, value);
                        __STATS__( false, io.flush.signal += 1; )
                }
                __STATS__( false, io.submit.extr += 1; )

                // to avoid dynamic allocation/memory reclamation headaches, wait for it to have been submitted
                wait( ei.waitctx );

                __cfadbg_print_safe(io, "Kernel I/O : %u submitted from arbiter\n", have);
        }

        // flush the io arbiter: move all external io operations to the submission ring
        static void __ioarbiter_flush( io_context$ & ctx, bool kernel ) {
                // if there are no external operations just return
                if(empty( ctx.ext_sq )) return;

                // stats and logs
                __STATS__( false, io.flush.external += 1; )
                __cfadbg_print_safe(io, "Kernel I/O : arbiter flushing\n");

                // this can happen from multiple processors, mutual exclusion is needed
                lock( ctx.ext_sq.lock __cfaabi_dbg_ctx2 );
                {
                        // pop each operation one at a time.
                        // There is no wait morphing because of the io sq ring
                        while( !ctx.ext_sq.queue`isEmpty ) {
                                // drop the element from the queue
                                __external_io & ei = (__external_io&)try_pop_front( ctx.ext_sq.queue );

                                // submit it
                                __submit_only(&ctx, ei.idxs, ei.have, true);

                                // wake the thread that was waiting on it
                                // since this can both be called from kernel and user, check the flag before posting
                                __post( ei.waitctx, kernel, UNPARK_LOCAL );
                        }

                        // mark the queue as empty
                        ctx.ext_sq.empty = true;
                        ctx.sq.last_external = true;
                }
                unlock(ctx.ext_sq.lock );
        }

        extern "C" {
                // debug functions used for gdb
                // io_uring doesn't yet support gdb soe the kernel-shared data structures aren't viewable in gdb
                // these functions read the data that gdb can't and should be removed once the support is added
                static __u32 __cfagdb_cq_head( io_context$ * ctx ) __attribute__((nonnull(1),used,noinline)) { return *ctx->cq.head; }
                static __u32 __cfagdb_cq_tail( io_context$ * ctx ) __attribute__((nonnull(1),used,noinline)) { return *ctx->cq.tail; }
                static __u32 __cfagdb_cq_mask( io_context$ * ctx ) __attribute__((nonnull(1),used,noinline)) { return *ctx->cq.mask; }
                static __u32 __cfagdb_sq_head( io_context$ * ctx ) __attribute__((nonnull(1),used,noinline)) { return *ctx->sq.kring.head; }
                static __u32 __cfagdb_sq_tail( io_context$ * ctx ) __attribute__((nonnull(1),used,noinline)) { return *ctx->sq.kring.tail; }
                static __u32 __cfagdb_sq_mask( io_context$ * ctx ) __attribute__((nonnull(1),used,noinline)) { return *ctx->sq.mask; }

                // fancier version that reads an sqe and copies it out.
                static struct io_uring_sqe __cfagdb_sq_at( io_context$ * ctx, __u32 at ) __attribute__((nonnull(1),used,noinline)) {
                        __u32 ax = at & *ctx->sq.mask;
                        __u32 ix = ctx->sq.kring.array[ax];
                        return ctx->sq.sqes[ix];
                }
        }
#endif