FFDB-012: Add benchmark and docs (#24)

README.md

@@ -0,0 +1,134 @@
+# FireflyDB
+
+FireflyDB is a fast, thread-safe, JVM-based key-value storage engine with microsecond latency. FireflyDB is 20x faster
+for reads and 10x faster for writes than [Bitcask](https://github.com/basho/bitcask), which has a similar architecture.
+
+FireflyDB is hash-based and gives up range queries to achieve high throughput and low latency. As a result, it is about
+100x faster at writes than [LevelDB](https://github.com/google/leveldb) (Google)
+and [RocksDB](https://github.com/facebook/rocksdb) (Facebook).
+
+FireflyDB relies on sensible defaults and does not expose many configuration options. FireflyDB is designed with
+educated tradeoffs to achieve high performance:
+
+1. All the keys must fit in memory. This is a tradeoff with all hash-based storage engines. Even with the largest key
+   size of 32KB, FireflyDB can store 32,000+ keys per 1GB of memory.
+2. FireflyDB does not support range queries.
+3. Maximum key size is 32768 bytes or 32KB.
+4. Maximum value size is 2,147,483,647 bytes or 2.14 GB.
+
+## Installation
+
+### Maven
+
+```xml
+
+<dependency>
+    <groupId>com.sahilbondre</groupId>
+    <artifactId>fireflydb</artifactId>
+    <version>0.1.0</version>
+</dependency>
+```
+
+### Gradle
+
+```gradle
+implementation 'com.sahilbondre:fireflydb:0.1.0'
+```
+
+## API
+
+```java
+FireflyDB fireflyDB=FireflyDB.getInstance("path/to/db");
+    fireflyDB.start();
+
+// Write
+    byte[]key="testKey".getBytes();
+    byte[]value="testValue".getBytes();
+
+    fireflyDB.put(key,value);
+
+// Read
+    byte[]result=fireflyDB.get(key);
+
+// Compaction 
+// FireflyDB will compact automatically but can be triggered on demand.
+    fireflyDB.compact();
+
+    fireflyDB.stop();
+```
+
+## Benchmarks
+
+```
+iterations: 100,000
+cpu: 1
+memory: 1GB
+key-size: 8 bytes
+value-size: 100 bytes
+```
+
+### Random Write Test
+
+Test: Generate a random key and value and write it to the database.
+
+![write-test](./docs/write-test.png)
+
+| Database  | Avg Time (microseconds) | P90 Latency (microseconds) |
+|-----------|-------------------------|----------------------------|
+| In-Memory | 0.53                    | 1                          |
+| LevelDB   | 445.94                  | 811                        |
+| Bitcask   | 71.33                   | 48                         |
+| RocksDB   | 568.60                  | 872                        |
+| FireflyDB | 7.10                    | 5                          |
+
+### Random Read Test
+
+Test: Pick a random key from the ones written in the previous test and read it from the database.
+
+![read-test](./docs/read-test.png)
+
+| Database  | Avg Time (microseconds) | P90 Latency (microseconds) |
+|-----------|-------------------------|----------------------------|
+| In-Memory | 0.49                    | 1                          |
+| LevelDB   | 1.55                    | 2                          |
+| Bitcask   | 108.03                  | 62                         |
+| RocksDB   | 0.94                    | 2                          |
+| FireflyDB | 4.97                    | 4                          |
+
+### Alternating Read-Write Test
+
+Test: Perform a read and write operation alternately.
+
+![alternating-read-write-test](./docs/rw-test.png)
+
+| Database          | Avg Time (microseconds) | P90 Latency (microseconds) |
+|-------------------|-------------------------|----------------------------|
+| In-Memory (read)  | 0.61                    | 1                          |
+| In-Memory (write) | 0.57                    | 1                          |
+| LevelDB (read)    | 3.43                    | 5                          |
+| LevelDB (write)   | 441.38                  | 814                        |
+| Bitcask (read)    | 120.15                  | 60                         |
+| Bitcask (write)   | 66.78                   | 57                         |
+| RocksDB (read)    | 4.54                    | 7                          |
+| RocksDB (write)   | 567.14                  | 971                        |
+| FireflyDB (read)  | 3.89                    | 4                          |
+| FireflyDB (write) | 3.91                    | 4                          |
+
+## Potential Improvements
+
+- [ ] Add an explicit delete operation.
+- [ ] Expose compaction size as a configuration option.
+- [ ] Expose compaction interval as a configuration option.
+- [ ] Allow larger key size as a configuration option.
+- [ ] Expose read only mode.
+
+## Contributing
+
+Pull requests are welcome. For major changes, please open an issue first
+to discuss what you would like to change.
+
+Please make sure to update tests as appropriate.
+
+## License
+
+[Apache 2.0](https://raw.githubusercontent.com/godcrampy/fireflydb/master/LICENSE)

benchmarks/firefly/.gitignore

@@ -0,0 +1,35 @@
+target/
+!.mvn/wrapper/maven-wrapper.jar
+!**/src/main/**/target/
+!**/src/test/**/target/
+
+### IntelliJ IDEA ###
+.idea/
+*.iws
+*.iml
+*.ipr
+
+### Eclipse ###
+.apt_generated
+.classpath
+.factorypath
+.project
+.settings
+.springBeans
+.sts4-cache
+
+### NetBeans ###
+/nbproject/private/
+/nbbuild/
+/dist/
+/nbdist/
+/.nb-gradle/
+build/
+!**/src/main/**/build/
+!**/src/test/**/build/
+
+### VS Code ###
+.vscode/
+
+### Mac OS ###
+.DS_Store

benchmarks/firefly/Dockerfile

@@ -0,0 +1,7 @@
+FROM eclipse-temurin:17-jre-jammy
+
+WORKDIR /app/firefly
+
+COPY ./target/benchmark-1.0-SNAPSHOT-jar-with-dependencies.jar /app/firefly/
+
+CMD ["java", "-jar", "benchmark-1.0-SNAPSHOT-jar-with-dependencies.jar"]

benchmarks/firefly/build_image.sh

@@ -0,0 +1,3 @@
+mvn clean compile assembly:single
+
+docker build -t fireflydb-benchmark-firefly .

benchmarks/firefly/delete_image.sh

@@ -0,0 +1 @@
+docker rmi fireflydb-benchmark-firefly

benchmarks/firefly/docker-compose.yml

@@ -0,0 +1,9 @@
+version: '3'
+services:
+  fireflydb-benchmark-bitcask:
+    image: fireflydb-benchmark-firefly
+    deploy:
+      resources:
+        limits:
+          cpus: '1'
+          memory: '1G'

benchmarks/firefly/pom.xml

@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>com.sahilbondre.fireflydb</groupId>
+    <artifactId>benchmark</artifactId>
+    <version>1.0-SNAPSHOT</version>
+
+    <properties>
+        <maven.compiler.source>17</maven.compiler.source>
+        <maven.compiler.target>17</maven.compiler.target>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>com.sahilbondre</groupId>
+            <artifactId>fireflydb</artifactId>
+            <version>0.1.0</version>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <!-- Build an executable JAR -->
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-assembly-plugin</artifactId>
+                <version>3.6.0</version>
+                <configuration>
+                    <archive>
+                        <manifest>
+                            <mainClass>com.sahilbondre.fireflydb.benchmark.Main</mainClass>
+                        </manifest>
+                    </archive>
+                    <descriptorRefs>
+                        <descriptorRef>jar-with-dependencies</descriptorRef>
+                    </descriptorRefs>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>