FasterKv.Cache

FasterKv.Cache是一个基于微软FasterKv封装的进程内混合缓存库(内存+磁盘)。FasterKv它可以承载大于机器内存的Key-Value数据库，并且有着远超其它内存+磁盘数据库的性能。不过使用起来比较繁琐，对新人不友好，于是FasterKv.Cache在它的基础上进行了一层封装，让我们能更简单的处理缓存。

笔者之前给EasyCaching提交了FasterKv的实现，但是由于有一些EasyCaching的高级功能在FasterKv上无法高性能的实现，所以单独创建了这个库，提供高性能和最基本的API实现；如果大家有使用EasyCaching那么一样可以直接使用EasyCaching.FasterKv。

NuGet 软件包

使用

直接使用

我们可以直接通过new FasterKvCache(...)的方式使用它，目前它只支持基本的三种操作Get、Set、Delete。为了方便使用和性能的考虑，我们将FasterKvCache分为两种API风格，一种是通用对象风格，一种是泛型风格。

• 通用对象：直接使用new FasterKvCache(...)创建，可以存放任意类型的Value。它底层使用object类型存储，所以内存缓冲内访问值类型对象会有装箱和拆箱的开销。
• 泛型：需要使用new FasterKvCache<T>(...)创建，只能存放T类型的Value。它底层使用T类型存储，所以内存缓冲内不会有任何开销。

当然如果内存缓冲不够，对应的Value被淘汰到磁盘上，那么同样都会有读磁盘、序列化和反序列化开销。

通用对象版本

代码如下所示，同一个cache实例可以添加任意类型：

using FasterKv.Cache.Core;
using FasterKv.Cache.Core.Configurations;
using FasterKv.Cache.MessagePack;

// create a FasterKvCache
var cache = new FasterKv.Cache.Core.FasterKvCache("MyCache",
    new DefaultSystemClock(),
    new FasterKvCacheOptions(),
    new IFasterKvCacheSerializer[]
    {
        new MessagePackFasterKvCacheSerializer
        {
            Name = "MyCache"
        }
    },
    null);

var key = Guid.NewGuid().ToString("N");

// sync 
// set key and value with expiry time
cache.Set(key, "my cache sync", TimeSpan.FromMinutes(5));

// get
var result = cache.Get<string>(key);
Console.WriteLine(result);

// get or add
result = cache.GetOrAdd(key, () => "my cache sync", TimeSpan.FromMinutes(5));
Console.WriteLine(result);

// delete
cache.Delete(key);

// async
// set
await cache.SetAsync(key, "my cache async");

// get
result = await cache.GetAsync<string>(key);
Console.WriteLine(result);

// get or add
result = await cache.GetOrAddAsync(key, () => "my cache async");
Console.WriteLine(result);

// delete
await cache.DeleteAsync(key);

// set other type object
cache.Set(key, new DateTime(2022,2,22));
Console.WriteLine(cache.Get<DateTime>(key));

输出结果如下所示：

my cache sync
my cache async
2022/2/22 0:00:00

泛型版本

泛型版本的话性能最好，但是它只允许添加一个类型，否则代码将编译不通过：

// create a FasterKvCache<T> 
// only set T type value
var cache = new FasterKvCache<string>("MyTCache",
    new DefaultSystemClock(),
    new FasterKvCacheOptions(),
    new IFasterKvCacheSerializer[]
    {
        new MessagePackFasterKvCacheSerializer
        {
            Name = "MyTCache"
        }
    },
    null);

Microsoft.Extensions.DependencyInjection

当然，我们也可以直接使用依赖注入的方式使用它，用起来也非常简单。按照通用和泛型版本的区别，我们使用不同的扩展方法即可：

var services = new ServiceCollection();
// use AddFasterKvCache
services.AddFasterKvCache(options =>
{
    // use MessagePack serializer
    options.UseMessagePackSerializer();
}, "MyKvCache");

var provider = services.BuildServiceProvider();

// get instance do something
var cache = provider.GetService<FasterKvCache>();

泛型版本需要调用相应的AddFasterKvCache<T>方法：

var services = new ServiceCollection();
// use AddFasterKvCache<string>
services.AddFasterKvCache<string>(options =>
{
    // use MessagePack serializer
    options.UseMessagePackSerializer();
}, "MyKvCache");

var provider = services.BuildServiceProvider();

// get instance do something
var cache = provider.GetService<FasterKvCache<string>>();

配置

FasterKvCache构造函数

public FasterKvCache(
    string name,											// 如果存在多个Cache实例，定义一个名称可以隔离序列化等配置和磁盘文件
    ISystemClock systemClock,								// 当前系统时钟，new DefaultSystemClock()即可
    FasterKvCacheOptions? options,							// FasterKvCache的详细配置，详情见下文
    IEnumerable<IFasterKvCacheSerializer>? serializers,		// 序列化器，可以直接使用MessagePack或SystemTextJson序列化器
    ILoggerFactory? loggerFactory)							// 日志工厂 用于记录FasterKv内部的一些日志信息

FasterKvCacheOptions 配置项

对于FasterKvCache，有着和FasterKv差不多的配置项，更详细的信息大家可以看FasterKv-Settings，下方是FasterKvCache的配置：

• IndexCount：FasterKv会维护一个hash索引池，IndexCount就是这个索引池的hash槽数量，一个槽为64bit。需要配置为2的次方。如1024(2的10次方)、 2048(2的11次方)、65536(2的16次方) 、131072(2的17次方)。默认槽数量为131072，占用1024kb的内存。
• MemorySizeBit: FasterKv用来保存Log的内存字节数，配置为2的次方数。默认为24，也就是2的24次方，使用16MB内存。
• PageSizeBit：FasterKv内存页的大小，配置为2的次方数。默认为20，也就是2的20次方，每页大小为1MB内存。
• ReadCacheMemorySizeBit：FasterKv读缓存内存字节数，配置为2的次方数，缓存内的都是热点数据，最好设置为热点数据所占用的内存数量。默认为20，也就是2的20次方，使用16MB内存。
• ReadCachePageSizeBit：FasterKv读缓存内存页的大小，配置为2的次方数。默认为20，也就是2的20次方，每页大小为1MB内存。
• LogPath：FasterKv日志文件的目录，默认会创建两个日志文件，一个以.log结尾，一个以obj.log结尾，分别存放日志信息和Value序列化信息，如果开启了DeleteFileOnClose和TryRecoverLatest，也会创建一个.checkpoint来进行故障恢复，注意，不要让不同的FasterKvCache使用相同的日志文件，会出现不可预料异常。默认为{当前目录}/FasterKvCache/{进程Id}-HLog/{实例名称}.log。
• SerializerName：Value序列化器名称，需要安装序列化Nuget包，如果没有单独指定Name的情况下，可以使用MessagePack和SystemTextJson。默认无需指定。
• PreallocateFile: 是否预分配日志文件，如果开启，那么在创建日志文件的时候会预分配指定1GB大小的文件，如果有大量数据的话，预分配能提升性能。默认为false。
• DeleteFileOnClose: 是否在关闭的时候删除日志文件，如果开启，那么在关闭的时候会删除日志文件，如果不开启，那么会保留日志文件，下次启动的时候会继续使用。默认为true。
• TryRecoverLatest: 是否在启动的时候尝试恢复最新的日志文件，如果开启，那么在启动的时候会尝试恢复最新的日志文件，如果不开启，那么会重新开始，如果要使它生效，需关闭DeleteFileOnClose。默认为false。
• ExpiryKeyScanInterval：由于FasterKv不支持过期删除功能，所以目前的实现是会定期扫描所有的key，将过期的key删除。这里配置的就是扫描间隔。默认为5分钟。
• CustomStore：如果您不想使用自动生成的实例，那么可以自定义的FasterKv实例。默认为null。

所以FasterKvCache所占用的内存数量基本就是(IndexCount*64)+(MemorySize)+ReadCacheMemorySize，当然如果Key的数量过多，那么还有加上OverflowBucketCount * 64。

容量规划

从上面提到的内容大家可以知道，FasterKvCache所占用的内存字节基本就是(IndexCount * 64)+(MemorySize) + ReadCacheMemorySize + (OverflowBucketCount * 64)。磁盘的话就是保存了所有的数据+对象序列化的数据，由于不同的序列化协议有不同的大小，大家可以先进行测试。

内存数据存储到FasterKv存储引擎，每个key都会额外元数据信息，存储空间占用会有一定的放大，建议在磁盘空间选择上，留有适当余量，按实际存储需求的 1.2 - 1.5倍预估。

如果使用内存存储 100GB 的数据，总的访问QPS不到2W，其中80%的数据都很少访问到。那么可以使用 【32GB内存 + 128GB磁盘】 存储，节省了近 70GB 的内存存储，内存成本可以下降50%+。

性能

目前作者还没有时间将FasterKvCache和其它主流的缓存库进行比对，现在只对FasterKvCache、EasyCaching.FasterKv和EasyCaching.Sqlite做的比较。下面是FasterKVCache的配置，总内存占用约为2MB。

services.AddFasterKvCache<string>(options =>
{
    options.IndexCount = 1024;
    options.MemorySizeBit = 20;
    options.PageSizeBit = 20;
    options.ReadCacheMemorySizeBit = 20;
    options.ReadCachePageSizeBit = 20;
    // use MessagePack serializer
    options.UseMessagePackSerializer();
}, "MyKvCache");

由于作者笔记本性能不够，使用Sqlite无法在短期内完成100W、1W个Key的性能测试，所以我们在默认设置下将数据集大小设置为1000个Key，设置50%的热点Key。进行100%读、100%写和50%读写随机比较。

可以看到无论是读、写还是混合操作FasterKvCache都有着不俗的性能，在8个线程情况下，TPS达到了惊人的1600w/s。

其它

项目目前已经用于生产环境，如果遇到BUG，请及时反馈问题，将在第一时间解决。