rt/mergerfs
1
0
Fork 0
mirror of https://github.com/trapexit/mergerfs.git synced 2026-10-26 19:01:56 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions
mergerfs/vendored/libfuse/include/fuse_lowlevel.h
Antonio S. Musumeci 8eed256747 Restore splice zero-copy I/O as runtime options 
Reinstate the splice read/write/move paths removed in 84592a9f, now
gated behind runtime options with negotiated pipe sizing and fallback
logging.

- Transport: msgbuf-piped splice receive, fd-referenced splice reply
  (vmsplice + splice), splice-move pipe-bounce, and restored
  fuse_buf_copy/fuse_buf_flags plumbing for copy fallbacks
- Negotiation: new pipe-max-size option (auto-raised at INIT when
  possible; the sysctl read/write is factored into src/pipe_max_size.cpp
  so fuse_init.cpp and option_parser.cpp share one implementation);
  fuse-msg-size clamped to what the pipe can hold; splice is disabled
  at INIT with a warning if the sysctl can't fit even the minimum,
  retracting the FUSE_CAP_SPLICE_* bits already advertised to the
  kernel in that case
- Read replies and splice-move are gated at 128 KiB (below that the
  syscalls cost more than the copy they avoid); every fallback path
  degrades to the copy path and logs once per process via SysLog
- msgbuf pipe cache is process-global and mutex-guarded (mutex_lockguard)
  so pipes can move between read and worker threads under
  process-thread mode
- API simplified after review: collapsed the three per-axis options
  (splice-read/write/move) into a single splice boolean (default on);
  no-splice-read/write/move and the bare splice-read/write/move
  spellings stay registered as accepted no-ops so existing mount
  options don't fail the mount, but they do NOT alter the splice
  knob - upgraders with no-splice-* in their config get splice
  enabled and must set splice=false explicitly (see
  deprecated_options.md)
- Fixed several correctness issues found in parallel review: a
  dropped write_buf registration that silently corrupted writes, a
  dirty-pipe reuse bug in msgbuf_free, an iov double-send in
  fuse_reply_data's splice-move fallback, and pipe-capacity math that
  assumed a 4096-byte page size
- Modernized the transport/negotiation code to this codebase's C++
  style: RAII (unique_ptr/DEFER) instead of malloc/free and manual fd
  close(), std::from_chars/to_chars instead of stoul/snprintf,
  _ReplyPipe's pipe ops as methods instead of free functions closing
  over a thread_local global, and vendored/libfuse/lib/buffer.cpp (a
  near-verbatim port of upstream's buffer.c) brought in line with the
  rest of the fork
- Documented splice and pipe-max-size options (mkdocs, FAQ,
  deprecated-options list); added tools/bench-splice.sh
- Benchmarked on tmpfs: seq_write +21%, seq_read +52%, small_write
  +5%, small_read +12%; validated with a 1h soak (~271 GiB
  hash-verified I/O, zero integrity failures), a live-mount round-trip
  of I/O above the splice threshold, and the existing unit/smoke
  suites at their pre-existing baseline

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-07 11:24:16 -04:00

554 lines
18 KiB
C
Raw Permalink Blame History

#pragma once
#include "extern_c.h"
#include "fuse_common.h"
#include "fuse_kernel.h"
#include "fuse_req.hpp"
#include <stdint.h>
#include <sys/stat.h>
#include <sys/statvfs.h>
#include <sys/types.h>
#include <sys/uio.h>
#include <utime.h>
EXTERN_C_BEGIN
/* ----------------------------------------------------------- *
* Miscellaneous definitions *
* ----------------------------------------------------------- */
/** The node ID of the root inode */
#define FUSE_ROOT_ID 1
/**
* Session
*
* This provides hooks for processing requests, and exiting
*/
struct fuse_session;
/** Directory entry parameters supplied to fuse_reply_entry() */
struct fuse_entry_param
{
/** Unique inode number
*
* In lookup, zero means negative entry (from version 2.5)
* Returning ENOENT also means negative entry, but by setting zero
* ino the kernel may cache negative entries for entry_timeout
* seconds.
*/
uint64_t ino;
/** Generation number for this entry.
*
* If the file system will be exported over NFS, the
* ino/generation pairs need to be unique over the file
* system's lifetime (rather than just the mount time). So if
* the file system reuses an inode after it has been deleted,
* it must assign a new, previously unused generation number
* to the inode at the same time.
*
* The generation must be non-zero, otherwise FUSE will treat
* it as an error.
*
*/
uint64_t generation;
/** Inode attributes.
*
* Even if attr_timeout == 0, attr must be correct. For example,
* for open(), FUSE uses attr.st_size from lookup() to determine
* how many bytes to request. If this value is not correct,
* incorrect data will be returned.
*/
struct stat attr;
fuse_timeouts_t timeout;
};
/* ----------------------------------------------------------- *
* Request methods and replies *
* ----------------------------------------------------------- */
/**
* Low level filesystem operations
*
* Most of the methods (with the exception of init and destroy)
* receive a request handle (fuse_req_t) as their first argument.
* This handle must be passed to one of the specified reply functions.
*
* This may be done inside the method invocation, or after the call
* has returned. The request handle is valid until one of the reply
* functions is called.
*
* Other pointer arguments (name, fuse_file_info, etc) are not valid
* after the call has returned, so if they are needed later, their
* contents have to be copied.
*
* The filesystem sometimes needs to handle a return value of -ENOENT
* from the reply function, which means, that the request was
* interrupted, and the reply discarded. For example if
* fuse_reply_open() return -ENOENT means, that the release method for
* this file will not be called.
*/
struct fuse_lowlevel_ops
{
void (*access)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*bmap)(fuse_req_t *req, const struct fuse_in_header *hdr);
void (*copy_file_range)(fuse_req_t *req, const struct fuse_in_header *hdr);
void (*create)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*destroy)();
void (*fallocate)(fuse_req_t *req, const struct fuse_in_header *hdr);
void (*flush)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*forget)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*forget_multi)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*fsync)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*fsyncdir)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*getattr)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*getxattr)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*init)(fuse_conn_info_t *conn);
void (*ioctl)(fuse_req_t *req, const struct fuse_in_header *hdr);
void (*link)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*listxattr)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*lookup)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*lseek)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*mkdir)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*mknod)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*open)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*opendir)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*poll)(fuse_req_t *req, const struct fuse_in_header *hdr);
void (*read)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*readdir)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*readdir_plus)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*readlink)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*release)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*releasedir)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*removemapping)(fuse_req_t *req, const struct fuse_in_header *hdr);
void (*removexattr)(fuse_req_t *req, const struct fuse_in_header *hdr);
void (*rename)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*rename2)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*retrieve_reply)(fuse_req_t *req, void *cookie, uint64_t ino, off_t offset);
void (*rmdir)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*setattr)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*setupmapping)(fuse_req_t *req, const struct fuse_in_header *hdr);
void (*setxattr)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*statfs)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*statx)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*symlink)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*syncfs)(fuse_req_t *req, const struct fuse_in_header *hdr);
void (*tmpfile)(fuse_req_t *req, const struct fuse_in_header *hdr);
void (*unlink)(fuse_req_t *req, struct fuse_in_header *hdr);
void (*write)(fuse_req_t *req, struct fuse_in_header *hdr);
};
/**
* Reply with an error code or success
*
* Possible requests:
* all except forget
*
* unlink, rmdir, rename, flush, release, fsync, fsyncdir, setxattr,
* removexattr may send a zero code
*
* @param req request handle
* @param err the positive error value, or zero for success
* @return zero for success, -errno for failure to send reply
*/
int fuse_reply_err(fuse_req_t *req, int err);
/**
* Don't send reply
*
* Possible requests:
* forget
*
* @param req request handle
*/
void fuse_reply_none(fuse_req_t *req);
/**
* Reply with a directory entry
*
* Possible requests:
* lookup, mknod, mkdir, symlink, link
*
* Side effects:
* increments the lookup count on success
*
* @param req request handle
* @param e the entry parameters
* @return zero for success, -errno for failure to send reply
*/
int fuse_reply_entry(fuse_req_t *req, const struct fuse_entry_param *e);
/**
* Reply with a directory entry and open parameters
*
* currently the following members of 'fi' are used:
* fh, direct_io, keep_cache
*
* Possible requests:
* create
*
* Side effects:
* increments the lookup count on success
*
* @param req request handle
* @param e the entry parameters
* @param fi file information
* @return zero for success, -errno for failure to send reply
*/
int fuse_reply_create(fuse_req_t *req,
const struct fuse_entry_param *e,
const fuse_file_info_t *fi);
/**
* Reply with attributes
*
* Possible requests:
* getattr, setattr
*
* @param req request handle
* @param attr the attributes
* @param attr_timeout validity timeout (in seconds) for the attributes
* @return zero for success, -errno for failure to send reply
*/
int fuse_reply_attr(fuse_req_t *req,
const struct stat *attr,
const uint64_t timeout);
int fuse_reply_statx(fuse_req_t *req,
int flags,
struct fuse_statx *st,
const uint64_t timeout);
/**
* Reply with the contents of a symbolic link
*
* Possible requests:
* readlink
*
* @param req request handle
* @param link symbolic link contents
* @return zero for success, -errno for failure to send reply
*/
int fuse_reply_readlink(fuse_req_t *req,
const char *linkname,
const size_t linkname_len);
/**
* Reply with open parameters
*
* currently the following members of 'fi' are used:
* fh, direct_io, keep_cache
*
* Possible requests:
* open, opendir
*
* @param req request handle
* @param fi file information
* @return zero for success, -errno for failure to send reply
*/
int fuse_reply_open(fuse_req_t *req,
const fuse_file_info_t *fi);
/**
* Reply with number of bytes written
*
* Possible requests:
* write
*
* @param req request handle
* @param count the number of bytes written
* @return zero for success, -errno for failure to send reply
*/
int fuse_reply_write(fuse_req_t *req, size_t count);
int fuse_reply_copy_file_range_64(fuse_req_t *req, size_t count);
/**
* Reply with data
*
* Possible requests:
* read, readdir, getxattr, listxattr
*
* @param req request handle
* @param buf buffer containing data
* @param size the size of data in bytes
* @return zero for success, -errno for failure to send reply
*/
int fuse_reply_buf(fuse_req_t *req, const char *buf, size_t size);
int fuse_reply_data_splice_fd(fuse_req_t *req,
const int src_fd,
const off_t pos,
const size_t size);
int fuse_reply_data(fuse_req_t *req,
char *buf,
size_t bufsize);
/**
* Reply with data vector
*
* Possible requests:
* read, readdir, getxattr, listxattr
*
* @param req request handle
* @param iov the vector containing the data
* @param count the size of vector
* @return zero for success, -errno for failure to send reply
*/
int fuse_reply_iov(fuse_req_t *req, const struct iovec *iov, int count);
/**
* Reply with filesystem statistics
*
* Possible requests:
* statfs
*
* @param req request handle
* @param stbuf filesystem statistics
* @return zero for success, -errno for failure to send reply
*/
int fuse_reply_statfs(fuse_req_t *req, const struct statvfs *stbuf);
/**
* Reply with needed buffer size
*
* Possible requests:
* getxattr, listxattr
*
* @param req request handle
* @param count the buffer size needed in bytes
* @return zero for success, -errno for failure to send reply
*/
int fuse_reply_xattr(fuse_req_t *req, size_t count);
/**
* Reply with block index
*
* Possible requests:
* bmap
*
* @param req request handle
* @param idx block index within device
* @return zero for success, -errno for failure to send reply
*/
int fuse_reply_bmap(fuse_req_t *req, uint64_t idx);
/**
* Reply to ask for data fetch and output buffer preparation. ioctl
* will be retried with the specified input data fetched and output
* buffer prepared.
*
* Possible requests:
* ioctl
*
* @param req request handle
* @param in_iov iovec specifying data to fetch from the caller
* @param in_count number of entries in in_iov
* @param out_iov iovec specifying addresses to write output to
* @param out_count number of entries in out_iov
* @return zero for success, -errno for failure to send reply
*/
int fuse_reply_ioctl_retry(fuse_req_t *req,
const struct iovec *in_iov, size_t in_count,
const struct iovec *out_iov, size_t out_count);
/**
* Reply to finish ioctl
*
* Possible requests:
* ioctl
*
* @param req request handle
* @param result result to be passed to the caller
* @param buf buffer containing output data
* @param size length of output data
*/
int fuse_reply_ioctl(fuse_req_t *req, int result, const void *buf, uint32_t size);
/**
* Reply with poll result event mask
*
* @param req request handle
* @param revents poll result event mask
*/
int fuse_reply_poll(fuse_req_t *req, unsigned revents);
/* ----------------------------------------------------------- *
* Notification *
* ----------------------------------------------------------- */
/**
* Notify IO readiness event
*
* For more information, please read comment for poll operation.
*
* @param ph poll handle to notify IO readiness event for
*/
int fuse_lowlevel_notify_poll(fuse_pollhandle_t *ph);
/**
* Notify to invalidate cache for an inode
*
* @param se the session through which to send the invalidation
* @param ino the inode number
* @param off the offset in the inode where to start invalidating
* or negative to invalidate attributes only
* @param len the amount of cache to invalidate or 0 for all
* @return zero for success, -errno for failure
*/
int fuse_lowlevel_notify_inval_inode(struct fuse_session *se, uint64_t ino,
off_t off, off_t len);
/**
* Notify to invalidate parent attributes and the dentry matching
* parent/name
*
* To avoid a deadlock don't call this function from a filesystem operation and
* don't call it with a lock held that can also be held by a filesystem
* operation.
*
* @param se the session through which to send the invalidation
* @param parent inode number
* @param name file name
* @param namelen strlen() of file name
* @return zero for success, -errno for failure
*/
int fuse_lowlevel_notify_inval_entry(struct fuse_session *se, uint64_t parent,
const char *name, size_t namelen);
/**
* Notify to invalidate parent attributes and delete the dentry matching
* parent/name if the dentry's inode number matches child (otherwise it
* will invalidate the matching dentry).
*
* To avoid a deadlock don't call this function from a filesystem operation and
* don't call it with a lock held that can also be held by a filesystem
* operation.
*
* @param se the session through which to send the notification
* @param parent inode number
* @param child inode number
* @param name file name
* @param namelen strlen() of file name
* @return zero for success, -errno for failure
*/
int fuse_lowlevel_notify_delete(struct fuse_session *se,
uint64_t parent, uint64_t child,
const char *name, size_t namelen);
/**
* Retrieve data from the kernel buffers
*
* Retrieve data in the kernel buffers belonging to the given inode.
* If successful then the retrieve_reply() method will be called with
* the returned data.
*
* Only present pages are returned in the retrieve reply. Retrieving
* stops when it finds a non-present page and only data prior to that is
* returned.
*
* If this function returns an error, then the retrieve will not be
* completed and no reply will be sent.
*
* This function doesn't change the dirty state of pages in the kernel
* buffer. For dirty pages the write() method will be called
* regardless of having been retrieved previously.
*
* @param se the session through which to send the invalidation
* @param ino the inode number
* @param size the number of bytes to retrieve
* @param offset the starting offset into the file to retrieve from
* @param cookie user data to supply to the reply callback
* @return zero for success, -errno for failure
*/
int fuse_lowlevel_notify_retrieve(struct fuse_session *se, uint64_t ino,
size_t size, off_t offset, void *cookie);
/* ----------------------------------------------------------- *
* Utility functions *
* ----------------------------------------------------------- */
/**
* Get the current supplementary group IDs for the specified request
*
* Similar to the getgroups(2) system call, except the return value is
* always the total number of group IDs, even if it is larger than the
* specified size.
*
* The current fuse kernel module in linux (as of 2.6.30) doesn't pass
* the group list to userspace, hence this function needs to parse
* "/proc/$TID/task/$TID/status" to get the group IDs.
*
* This feature may not be supported on all operating systems. In
* such a case this function will return -ENOSYS.
*
* @param req request handle
* @param size size of given array
* @param list array of group IDs to be filled in
* @return the total number of supplementary group IDs or -errno on failure
*/
int fuse_req_getgroups(fuse_req_t *req, int size, gid_t list[]);
/* ----------------------------------------------------------- *
* Filesystem setup *
* ----------------------------------------------------------- */
/* Deprecated, don't use */
int fuse_lowlevel_is_lib_option(const char *opt);
/**
* Create a low level session
*
* @param args argument vector
* @param op the low level filesystem operations
* @param op_size sizeof(struct fuse_lowlevel_ops)
* @return the created session object, or NULL on failure
*/
struct fuse_session *fuse_lowlevel_new(struct fuse_args *args,
const struct fuse_lowlevel_ops *op,
size_t op_size);
/* ----------------------------------------------------------- *
* Session interface *
* ----------------------------------------------------------- */
struct fuse_session *fuse_session_new(void *data,
void *receive_buf,
void *process_buf,
void *destroy);
void fuse_session_destroy(struct fuse_session *se);
void fuse_session_exit(struct fuse_session *se);
int fuse_session_exited(struct fuse_session *se);
void fuse_session_reset(struct fuse_session *se);
void *fuse_session_data(struct fuse_session *se);
int fuse_session_receive(struct fuse_session *se,
struct fuse_buf *buf);
void fuse_session_process(struct fuse_session *se,
const void *buf,
const size_t bufsize);
int fuse_session_loop_mt(struct fuse_session *se,
const int read_thread_count,
const int process_thread_count,
const int process_thread_queue_depth,
const char *pin_threads_type);
/* Direct file descriptor and buffer size accessors
* (channel fields inlined into session for single-mount simplicity) */
int fuse_session_fd(struct fuse_session *se);
size_t fuse_session_bufsize(struct fuse_session *se);
int fuse_session_clearfd(struct fuse_session *se);
void fuse_session_setfd(struct fuse_session *se, int fd);
void fuse_session_setbufsize(struct fuse_session *se, size_t bufsize);
EXTERN_C_END
Reference in a new issue View git blame Copy permalink