Project: Gluster (Runtime / Cloud Native Storage)
File: fuse-interrupt.md

FUSE refers to the "wire protocol" between kernel and userspace and related specifications. fuse refers to the kernel subsystem and also to the GlusterFs translator. The desrcibes how interrupt handling happens in fuse. This document describes the internal API in the fuse translator with which interrupt can be handled. The API being internal (to be used only in fuse-bridge.c; the functions are not exported to a header file). ``` enum fuseinterruptstate { / ... / INTERRUPT_SQUELCHED, INTERRUPT_HANDLED, / ... / }; typedef enum fuseinterruptstate fuseinterruptstate_t; struct fuseinterruptrecord; typedef struct fuseinterruptrecord fuseinterruptrecord_t; typedef void (fuse_interrupt_handler_t)(xlator_t this, fuseinterruptrecord_t *); struct fuseinterruptrecord { fuseinheadert fusein_header; void *data; /* ... */ }; fuseinterruptrecord_t * fuseinterruptrecordnew(fuseinheadert *finh, fuseinterrupthandler_t handler); void fuseinterruptrecordinsert(xlatort this, fuse_interrupt_record_t fir); gfbooleant fuseinterruptfinishfop(callframet *frame, xlatort *this, gfbooleant sync, void datap); void fuseinterruptfinishinterrupt(xlatort this, fuse_interrupt_record_t fir, fuseinterruptstate_t intstat, gfbooleant sync, void datap); ``` The code demonstrates the usage of the API through `fuse_flush()`. (It's a dummy implementation only for demonstration purposes.) Flush is chosen because a `FLUSH` interrupt is easy to trigger (see tests/features/interrupt.t). Interrupt handling for flush is switched on by `--fuse-flush-handle-interrupt` (a hidden glusterfs command line flag). The implementation of flush interrupt is contained in the `fuseflushinterrupt_handler()` function and blocks guarded by the ``` if (priv->flushhandleinterrupt) { ... ``` conditional (where `priv` is a `*fuseprivatet`). "Regular" fuse fops and interrupt handlers interact via a list containing interrupt records. If a fop wishes to have its interrupts handled, it needs to set up an interrupt record and insert it into the list; also when it's to finish (ie. in its "cbk" stage) it needs to delete the record from the list. If no interrupt happens, basically that's all to it - a list insertion and deletion. However, if an interrupt comes for the fop, the interrupt FUSE request will carry the data identifying an ongoing fop (that is, its `unique`), and based on that, the interrupt record will be looked up in the list, and the specific interrupt handler (a member of the interrupt record) will be called. Usually the fop needs to share some data with the interrupt handler to enable it to perform its task (also shared via the interrupt record). The interrupt API offers two approaches to manage shared data: Async or reference-counting strategy: from the point on when the interrupt record is inserted to the list, it's owned jointly by the regular fop and the prospective interrupt handler. Both of them need to check before they return if the other is still holding a reference; if not, then they are responsible for reclaiming the shared

Sync or borrow strategy: the interrupt handler is considered a borrower of the shared data. The interrupt handler should not reclaim the shared data. The fop will wait for the interrupt handler to finish (ie., the borrow to be returned), then it has to reclaim the shared data. The user of the interrupt API need to call the following functions to instrument this control flow: `fuseinterruptrecord_insert()` in the fop to insert the interrupt record to the list; `fuseinterruptfinish_fop()`in the fop (cbk) and `fuseinterruptfinish_interrupt()`in the interrupt handler to perform needed synchronization at the end their tenure. The data management strategies are implemented by the `fuseinterruptfinish_*()` functions (which have an argument to specify which strategy to use); these routines take care of freeing the interrupt record itself, while the reclamation of the shared data is left to the API user. A given FUSE fop can be enabled to handle interrupts via the following steps: Define a handler function (of type `fuseinterrupthandler_t`). It should implement the interrupt handling logic and in the end call (directly or as async callback) `fuseinterruptfinish_interrupt()`. The `intstat` argument to `fuseinterruptfinish_interrupt` should be either `INTERRUPTSQUELCHED` or `INTERRUPTHANDLED`. `INTERRUPT_SQUELCHED` means that the interrupt could not be delivered and the fop is going on uninterrupted. `INTERRUPT_HANDLED` means that the interrupt was actually handled. In this case the fop will be answered from interrupt context with errno `EINTR` (that is, the fop should not send a response to the kernel). (the enum `fuseinterruptstate` includes further members, which are reserved for internal use). We return to the `sync` and `datap` arguments later. In the `fuse_<FOP>` function create an interrupt record using `fuseinterruptrecordnew()`, passing the incoming `fusein_header` and the above handler function to it. Arbitrary further data can be referred to via the `data` member of the interrupt record that is to be passed on from fop context to interrupt context. When it's set up, pass the interrupt record to `fuseinterruptrecord_insert()`. In `fuse<FOP>cbk` call `fuseinterruptfinish_fop()`. `fuseinterruptfinish_fop()` returns a Boolean according to whether the interrupt was handled. If it was, then the FUSE request is already answered and the stack gets destroyed in `fuseinterruptfinish_fop` so `fuse<FOP>cbk()` can just return (zero). Otherwise follow the standard cbk logic (answer the FUSE request and destroy the stack -- these are typically accomplished by `fuseerrcbk()`). The last two argument of `fuseinterruptfinish_fop()` and `fuseinterruptfinishinterrupt()` are `gfboolean_t sync` and `void datap`. `sync` represents the strategy for freeing the interrupt record. The interrupt handler and the fop handler are in race to get at the interrupt record first (interrupt handler for purposes of doing the interrupt handling, fop handler for purposes of deactivating the interrupt record upon completion of the fop

If `sync` is true, then the fop handler will wait for the interrupt handler to finish and it takes care of freeing. If `sync` is false, the loser of the above race will perform freeing. Freeing is done within the respective interrupt finish routines, except for the `data` field of the interrupt record; with respect to that, see the discussion of the `datap` parameter below. The strategy has to be consensual, that is, `fuseinterruptfinish_fop()` and `fuseinterruptfinish_interrupt()` must pass the same value for `sync`. If dismantling the resources associated with the interrupt record is simple, `sync = gffalse` is the suggested choice; `sync = gftrue` can be useful in the opposite case, when dismantling those resources would be inconvenient to implement in two places or to enact in non-fop context. If `datap` is `NULL`, the `data` member of the interrupt record will be freed within the interrupt finish routine. If it points to a valid `void *` pointer, and if caller is doing the cleanup (see `sync` above), then that pointer will be directed to the `data` member of the interrupt record and it's up to the caller what it's doing with it. If `sync` is true, interrupt handler can use `datap = NULL`, and fop handler will have `datap` point to a valid pointer. If `sync` is false, and handlers pass a pointer to a pointer for `datap`, they should check if the pointed pointer is NULL before attempting to deal with the data. The kernel acknowledges a successful interruption for a given FUSE request if the filesystem daemon answers it with errno EINTR; upon that, the syscall which induced the request will be abruptly terminated with an interrupt, rather than returning a value. In glusterfs, this can be arranged in two ways. If the interrupt handler wins the race for the interrupt record, ie. `fuseinterruptfinishfop()` returns true to `fuse<FOP>_cbk()`, then, as said above, `fuse<FOP>cbk()` does not need to answer the FUSE request. That's because then the interrupt handler will take care about answering it (with errno EINTR). If `fuseinterruptfinishfop()` returns false to `fuse<FOP>_cbk()`, then this return value does not inform the fop handler whether there was an interrupt or not. This return value occurs both when fop handler won the race for the interrupt record against the interrupt handler, and when there was no interrupt at all. However, the internal logic of the fop handler might detect from other circumstances that an interrupt was delivered. For example, the fop handler might be sleeping, waiting for some data to arrive, so that a premature wakeup (with no data present) occurs if the interrupt handler intervenes. In such cases it's the responsibility of the fop handler to reply the FUSE request with errro EINTR.