merging v3 to main for a base (#7)

* restructure

* in-flight structs

* queue creation and submition

* handle completion init

* main:v1::3

* traiing fix getdent64()

* imp: custom  #6

* make change

* Moving Hybrid

* recursive-tree init

* minor typo : : awating approval #6

* tested
- Adding build files

* code cleanup
awaiting approval
awaiting build files

* tested
- adding build file

* [STAGE] merge-step-1

* chaning

* check

* pushing readmes

* usage update

* changing

* readme edit

* readme edit

* readme edit

* Add MIT License to the project

* Add LICENSE file

* Add LICENSE file

* Add GNUL license file

* adding licence

* redo

* Add MIT License file

* adding LGNU

* adding licences

* add: debian

* add: debian builds

Author: ArchitAnant

.gitignore

@@ -3,3 +3,4 @@ testdir
 ffind.*
 .vscode/
 temp.md
+.DS_Store

COPYING

@@ -0,0 +1,22 @@
+
+MIT License
+
+Copyright (c) 2025 Archit Anant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

COPYING.GPL

@@ -1,33 +1,47 @@
-# Compiler and flags
-CC = gcc
-CFLAGS = -Wall -Iinclude -g    # -g for debugging symbols
+CC       := gcc
+INC_DIR  := headers
 
-# Source and build directories
-SRC_DIR = src
-BUILD_DIR = build
-SRC = $(SRC_DIR)/main.c $(SRC_DIR)/workqueue.c $(SRC_DIR)/worker.c
-OBJ = $(SRC:%.c=$(BUILD_DIR)/%.o)
+# Use pkg-config if available for liburing
+PKG_CFLAGS := $(shell pkg-config --cflags liburing 2>/dev/null)
+PKG_LIBS   := $(shell pkg-config --libs liburing 2>/dev/null)
 
-# Target binary
-TARGET = $(BUILD_DIR)/ffind
+CFLAGS  := -Wall -Wextra -O2 -I$(INC_DIR) $(PKG_CFLAGS)
+LDLIBS  := $(if $(PKG_LIBS),$(PKG_LIBS),-luring)
 
-# Ensure build directory exists
-$(shell mkdir -p $(BUILD_DIR)/$(SRC_DIR))
+SRC_DIR   := src
+BUILD_DIR := build
+
+# Source and object files
+SRCS   := $(wildcard $(SRC_DIR)/*.c)
+OBJS   := $(patsubst $(SRC_DIR)/%.c,$(BUILD_DIR)/%.o,$(SRCS))
+TARGET := $(BUILD_DIR)/ffind
+
+# Install prefix (Debian packaging overrides with DESTDIR + PREFIX=/usr)
+PREFIX  ?= /usr
+BINDIR  := $(PREFIX)/bin
 
-# Default rule
 all: $(TARGET)
 
-# Link object files to create the binary
-$(TARGET): $(OBJ)
-	$(CC) $(OBJ) -o $(TARGET)
+$(TARGET): $(OBJS) | $(BUILD_DIR)
+	$(CC) $(CFLAGS) -o $@ $^ $(LDLIBS)
 
-# Compile source files to object files
-$(BUILD_DIR)/%.o: %.c
+$(BUILD_DIR)/%.o: $(SRC_DIR)/%.c $(INC_DIR)/submissions.h | $(BUILD_DIR)
 	$(CC) $(CFLAGS) -c $< -o $@
 
-# Clean build artifacts
+$(BUILD_DIR):
+	mkdir -p $(BUILD_DIR)
+
+install: $(TARGET)
+	mkdir -p $(DESTDIR)$(BINDIR)
+	cp $(TARGET) $(DESTDIR)$(BINDIR)/ffind
+
+uninstall:
+	rm -f $(DESTDIR)$(BINDIR)/ffind
+
 clean:
 	rm -rf $(BUILD_DIR)
 
-.PHONY: all clean
+run: $(TARGET)
+	./$(TARGET) testdir
 
+.PHONY: all clean run install uninstall

LICENCE

@@ -0,0 +1,77 @@
+
+
+ffind
+-----
+
+An Asynchronous File Finder for Linux
+
+ffind is a high-performance, command-line utility for recursively finding files on a Linux filesystem. It is built from the ground up using io_uring, the modern asynchronous I/O interface in the Linux kernel, to achieve maximum throughput and efficiency.
+
+ffind is designed to do one thing exceptionally well: find files that contain a specific substring in their name, as fast as possible. 
+
+
+
+Usage
+_____
+
+CHECK :: USAGE.md
+
+
+
+Working
+_______
+
+The Asynchronous io_uring Engine :
+
+ffind achieves its performance by fundamentally changing the conversation with the Linux kernel. Instead of the traditional "ask and wait" (blocking) model, ffind uses an event-driven, asynchronous architecture.
+
+
+The Core Components :
+
+io_uring : The foundation of the application. ffind initializes an io_uring instance, creating two ring buffers in memory that are shared directly with the kernel: the Submission Queue (SQ) and the Completion Queue (CQ). This shared memory allows for extremely low-overhead communication.
+
+
+The Event Loop : 
+
+The application is built around a single-threaded event loop in main(). This loop's only job is to manage the flow of I/O operations:
+- Submit pending requests from the SQ to the kernel.
+- Wait for completion events (CQEs) to appear on the CQ.
+- Dispatch completed events to a handler function.
+- Repeat.
+
+The State Machine (handle_completion) : 
+
+The heart of the logic resides in the handle_completion function. Since operations are asynchronous and can complete in any order, a state machine is used to track the progress of each directory scan. 
+
+A single Request struct holds the state for scanning one directory, transitioning through different phases:
+
+- Open Phase: 
+An openat operation is submitted. When it completes, the function receives a file descriptor (fd).
+
+- Read Phase: 
+The function stores the fd in the Request struct and submits a getdents64 operation (using the IORING_OP_READ opcode on the directory fd) to read the directory's contents.
+
+- Process and Recurse: 
+When the read completes, the buffer of directory entries is processed. For each subdirectory found, a new openat request is submitted, creating a new task. For each file, the name is checked against the search term.
+
+- Terminal State:
+When a directory read returns 0 bytes, the directory scan is complete. The file descriptor is closed, and all associated memory is freed.
+
+
+Targeting Efficiency :
+
+- Reduced System Call Overhead : The most expensive part of traditional I/O is the context switch between user space and kernel space for each system call. With io_uring, ffind can submit a large batch of I/O requests with a single syscall, and reap many completions with another. This drastically reduces the number of context switches.
+
+- True Asynchronicity : ffind can have hundreds or thousands of filesystem operations "in-flight" simultaneously. While the kernel is working on opening one directory or reading another, the application's CPU is free to process the results of already-completed operations. This keeps the CPU and the storage device constantly busy, maximizing parallelism.
+
+- Kernel-Side Polling (Optional) : For ultimate low-latency, io_uring can be configured to use kernel-side polling (IORING_SETUP_SQPOLL), which can eliminate system calls from the submission path almost entirely under heavy load.
+
+
+License
+-------
+
+All software contained within this repo is dual licensed LGPL and MIT. 
+
+
+Archit Anant 2025-09-23
+

Makefile

@@ -0,0 +1,31 @@
+## Usage
+**Prerequisites**
+ffind requires a modern Linux kernel (5.10+ recommended) and the liburing development library.
+
+### On Debian/Ubuntu
+```shell 
+sudo apt-get install build-essential liburing-dev
+# you can search for equivalent packages for Arch/Fedora.
+```
+### Compile the application
+```shell
+make
+```
+
+### Clean up build files
+```bash
+make clean
+```
+### Examples
+```shell
+./ffind <path> <search_term>
+
+# Search for all files containing "config" in your home directory
+./ffind ~ config
+
+# Search for all header files containing "net" in /usr/include
+./ffind /usr/include net
+
+# Find all Markdown files in the current directory
+./ffind . .md
+```

README

@@ -0,0 +1,5 @@
+ffind (1.0-1) unstable; urgency=medium
+
+  * Initial release (Closes: #000000)
+
+ -- Archit Anant <[email protected]>  Sat, 23 Aug 2025 20:00:00 +0530

README.md

@@ -0,0 +1,14 @@
+Source: ffind
+Section: utils
+Priority: optional
+Maintainer: Archit Anant <[email protected]>
+Build-Depends: debhelper-compat (= 13), pkg-config, liburing-dev
+Standards-Version: 4.6.2
+Rules-Requires-Root: no
+
+Package: ffind
+Architecture: any
+Depends: ${shlibs:Depends}, ${misc:Depends}, liburing2
+Description: Fast file finder using io_uring
+ ffind is a fast alternative to find files, implemented using Linux io_uring.
+