跳到主要内容

服务器端原始字符串扩展

自定义原始字符串扩展允许添加操作原始字符串的新函数，并将其注册到 Garnet。然后，可以从任何 Garnet 客户端调用此注册函数，并在 Garnet 服务器上执行。

开发自定义服务器端原始字符串扩展​

CustomRawStringFunctions 是所有自定义原始字符串函数的基类。要开发新函数，必须扩展此基类，然后包含自定义逻辑。在一个新的自定义原始字符串函数中，有六种方法需要实现：

  • GetInitialLength(ref RawStringInput input):
    GetInitialLength 方法返回使用给定输入通过 RMW 填充时值的初始预期长度。
  • GetLength(ReadOnlySpan<byte> value, ref RawStringInput input)
    GetLength 方法返回使用给定输入执行值的 RMW 修改时结果值对象的长度。
  • InitialUpdater(ReadOnlySpan<byte> key, ref RawStringInput input, Span<byte> value, ref RespMemoryWriter writer, ref RMWInfo rmwInfo)
    InitialUpdater 方法执行 RMW 的初始更新，给定键 (key)、给定输入 (input)、要插入的结果值 (value)、用于输出 input 操作在 value 上的结果的写入器 (writer) 以及此记录的记录信息引用（用于锁定） (rmwInfo)。
  • InPlaceUpdater(ReadOnlySpan<byte> key, ref RawStringInput input, Span<byte> value, ref int valueLength, ref RespMemoryWriter writer, ref RMWInfo rmwInfo)
    InPlaceUpdater 方法执行 RMW 的原地更新，给定键 (key)、用于计算更新值的给定输入 (input)、要更新的目标 (value)、用于输出 input 操作在 value 上的结果的写入器 (writer) 以及此记录的记录信息引用（用于锁定） (rmwInfo)。
  • CopyUpdater(ReadOnlySpan<byte> key, ref RawStringInput input, ReadOnlySpan<byte> oldValue, Span<byte> newValue, ref RespMemoryWriter writer, ref RMWInfo rmwInfo)
    CopyUpdate 方法执行 RMW 的复制更新，给定键 (key)、用于从 oldValue 计算 newValue 的给定输入 (input)、要复制/更新的先前值 (oldValue)、要更新的目标 (newValue)、复制 newValue 的写入器 (writer) 以及此记录的记录信息引用（用于锁定） (rmwInfo)。
  • Reader(ReadOnlySpan<byte> key, ref RawStringInput input, ReadOnlySpan<byte> value, ref RespMemoryWriter writer, ref ReadInfo readInfo);
    Reader 方法执行记录读取，给定要读取记录的键 (key)、用于从 value 计算 writer 的用户输入 (input)、正在读取记录的值 (value)、用于输出 value 的写入器 (writer) 以及此记录的记录信息引用（用于锁定） (rmwInfo)。

还有两个可选方法需要实现：

  • NeedInitialUpdate(ReadOnlySpan<byte> key, ref RawStringInput input, ref RespMemoryWriter writer)
    NeedInitialUpdate 确定是否应调用 RMW 的复制更新，给定记录的键 (key)、用于计算更新值的用户输入 (value) 以及要复制 input 操作结果的位置。
    注意： 如果此方法未被重写，则默认返回 true。
  • NeedCopyUpdate(ReadOnlySpan<byte> key, ref RawStringInput input, ReadOnlySpan<byte> oldValue, ref RespMemoryWriter writer)
    NeedCopyUpdate 确定是否应调用 RMW 的复制更新，给定记录的键 (key)、用于计算更新值的用户输入 (value)、要复制的现有值 (oldValue) 以及要复制 input 操作在 oldValue 上的结果的位置。
    注意： 如果此方法未被重写，则默认返回 true。

这些是开发自定义事务的辅助方法。

  • GetNextArg(ref RawStringInput input, scoped ref int offset):
    GetNextArg 方法用于在指定偏移量处从输入中检索下一个参数。它接受表示输入的 ArgSlice 参数和 int 偏移量的引用。它返回表示参数作为跨度的 ArgSlice 对象。该方法内部读取带有长度标头的指针以提取参数。
  • GetFirstArg(ref RawStringInput input):
    GetFirseArg 方法用于在偏移量 0 处从输入中检索参数。

通过在 Garnet 服务器对象的 RegisterAPI 对象上调用 NewCommand(string name, int numParams, CommandType type, CustomRawStringFunctions customFunctions, long expirationTicks = 0) 方法来注册自定义原始字符串函数，并提供其名称、参数数量、CommandType（Read / ReadModifyWrite）、自定义原始字符串函数类的实例，以及可选的过期时间（以 tick 为单位）。
也可以从客户端注册自定义原始字符串函数（作为管理命令，假设代码已经驻留在服务器上），方法是使用 REGISTERCS 命令（请参阅自定义命令）。