Server-Side Raw-String Extensions
Custom raw-string extensions allows adding new functions that operate on raw strings and registering them with Garnet. This registered function can then be invoked from any Garnet client and be executed on the Garnet server.
Developing custom server side Raw-String Extensions
CustomRawStringFunctions
is the base class for all custom raw-string functions. To develop a new one, this class has to be extended and then include the custom logic. There are six methods to be implemented in a new custom raw-string function:
GetInitialLength(ReadOnlySpan<byte> input)
:
TheGetInitialLength
method returns the length of the initial expected length of value when populated by RMW using given inputGetLength(ReadOnlySpan<byte> value, ReadOnlySpan<byte> input)
TheGetLength
method returns the length of resulting value object when performing RMW modification of value using given inputInitialUpdater(ReadOnlySpan<byte> key, ReadOnlySpan<byte> input, Span<byte> value, ref (IMemoryOwner<byte>, int) output, ref RMWInfo rmwInfo)
TheInitialUpdater
method makes an initial update for RMW, given the key (key
), the given input (input
), the resulting value to be inserted (value
), the location where the result of theinput
operation onvalue
is to be copied (output
) and the reference for the record info for this record (used for locking) (rmwInfo
)InPlaceUpdater(ReadOnlySpan<byte> key, ReadOnlySpan<byte> input, Span<byte> value, ref int valueLength, ref (IMemoryOwner<byte>, int) output, ref RMWInfo rmwInfo)
TheInPlaceUpdater
method performs an in-place update for RMW, given the key (key
), the given input for computing the updated (input
), the destination to be updated (value
), the location where the result of theinput
operation onvalue
is to be copied (output
) and the location whereCopyUpdater(ReadOnlySpan<byte> key, ReadOnlySpan<byte> input, ReadOnlySpan<byte> oldValue, Span<byte> newValue, ref (IMemoryOwner<byte>, int) output, ref RMWInfo rmwInfo)
TheCopyUpdate
method performs a copy update for RMW, given the key (key
), the given input for computingnewValue
fromoldValue
(input
), the previous value to be copied/updated (oldValue
), the destination to be updated (newValue
), the location where thenewValue
is to be copied (output
) and the reference for the record info for this record (used for locking) (rmwInfo
)Reader(ReadOnlySpan<byte> key, ReadOnlySpan<byte> input, ReadOnlySpan<byte> value, ref (IMemoryOwner<byte>, int) output, ref ReadInfo readInfo);
TheReader
method performs a record read, given the key for the record to be read (key
), the user input for computingoutput
fromvalue
(input
), the value for the record being read (value
), the location wherevalue
is to be copied (output
) and the reference for the record info for this record (used for locking) (rmwInfo
)
There are two other optional methods to be implemented:
NeedInitialUpdate(ReadOnlySpan<byte> key, ReadOnlySpan<byte> input, ref (IMemoryOwner<byte>, int) output)
TheNeedInitialUpdate
determines whether copy-update for RMW should be invoked, given the key for the record (key
), the user input to be used for computing the updated value (value
) and the location where the result of theinput
operation is to be copied.
Note: If this method is not overridden, it returnstrue
by defaultNeedCopyUpdate(ReadOnlySpan<byte> key, ReadOnlySpan<byte> input, ReadOnlySpan<byte> oldValue, ref (IMemoryOwner<byte>, int) output)
TheNeedCopyUpdate
determines whether copy-update for RMW should be invoked, given the key for the record (key
), the user input to be used for computing the updated value (value
), the existing value that would be copied (oldValue
) and the location where the result of theinput
operation onoldValue
is to be copied.
Note: If this method is not overridden, it returnstrue
by default
These are the helper methods for developing custom transactions.
GetNextArg(ArgSlice input, ref int offset)
:
TheGetNextArg
method is used to retrieve the next argument from the input at the specified offset. It takes an ArgSlice parameter representing the input and a reference to an int offset. It returns an ArgSlice object representing the argument as a span. The method internally reads a pointer with a length header to extract the argument.GetFirstArg(ReadOnlySpan<byte> input)
:
TheGetFirseArg
method is used to retrieve the argument from the input at offset 0.
Registering the custom raw-string function is done on the server-side by calling the NewCommand(string name, int numParams, CommandType type, CustomRawStringFunctions customFunctions, long expirationTicks = 0)
method on the Garnet server object's RegisterAPI
object with its name, number of parameters, the CommandType (Read / ReadModifyWrite), an instance of the custom raw-string function class, and optionally the number of ticks for expiration.
It is possible to register the custom raw-string function from the client-side as well (as an admin command, given that the code already resides on the server) by using the REGISTER
command (see Custom Commands).