Skip to main content

Onboarding for Garnet Development

Welcome to Garnet! In this page, you will find the main steps to set up your work environment for developing in Garnet.

Quick start & useful resources​

For an introduction to Garnet and its capabilities, you can start with Welcome to Garnet page.

Additionally the following pages and documentation might be helpful:

Tools​

  • Visual Studio 2022 (Preview version recommended)
  • .NET 8.x
  • Git
  • Azure Windows VM
  • Azure Linux VM
  • An interactive RESP client, such as
    • On Linux: redis-cli, interactive RESP client in Linux
    • On Windows: Memurai (for using memurai-cli client) or redis-cli via WSL
    • RedisInsight for experimenting with contents of the store
    • telnet

Start hacking​

  1. Clone the repository

git clone https://github.com/microsoft/garnet.git

After cloning the repository you can either run the unit tests or run the server and use one of the RESP client suggested in Windows or Linux.

  1. Run the tests suite
    dotnet test -c Release -l "console;verbosity=detailed"

  1. Run the server

    Using a size memory of 4 GB and index size of 64 MB:

    cd <root>/main/GarnetServer/

    dotnet run -c Debug -f net8.0 -- --logger-level Trace -m 4g -i 64m

  2. Use the Memurai client in Windows to send commands to Garnet. A guide about how to install Memurai on Windows can be found here.

  3. If you are using Linux, you can use the redis-cli tool. Our official supported Linux distribution is Ubuntu.

  4. A third option is to install Redis-Insight on Windows. Follow the official guide here.

Troubleshooting​

  1. If you need to use tls in linux follow the guide at:

    <root>/Garnet/test/testcerts/README.md

  2. If you need to run the local device library make sure to have these dependencies:

    sudo apt install -y g++ libaio-dev uuid-dev libtbb-dev

Garnet API development​

Code Patterns​

All requests to the server are either basic RESP commands or array RESP commands. The following shows one example of each of them:

Basic Command: PING RESP representation:

$4\r\nPING\r\n

Array Command: SET mykey abc

RESP representation:

*3\r\n$3\r\nSET\r\n$5\r\nmykey\r\n$7\r\nabcdefg\r\n

Development concepts​

  • Understanding of the types of memory in C#: Managed Heap, Stack memory, Unmanaged memory, etc.

  • Use of Span and SpanByte

    Tsavorite and Garnet rely heavily on these two types for allocating data in memory and then transfer it on the network layer. Understanding and familiarity with both of them will be very helpful for a better understanding of the code in general.

Pull Request protocol​

Any new feature, change to existing functionality or bug fixing needs to be done using the following process:

  1. Create a Issue Item on the Garnet Project, use the following criteria: Enhancement for new features, Bug for fixes, Task for small improvements or changes.

  2. Is a good practice to create your own local branch with the following naming convention:

    <username>/branch-name

  3. Include Unit Tests to test the new commands or feature.

  4. Once it is ready for review, create a Pull Request. Make sure to link it to your issue item in the development section.

Formatting style guide​

  • Comments are an important part of the documentation. Make sure your code includes them.

  • The official format for comments is:

    //<one whitespace> Comment starting with a capital letter

    Example:

    // This comment has good formatting

  • Methods should have their summary block comment and description for each parameter.

    Example:


/// <summary>
/// Iterates the set of keys in the main store.
/// </summary>
/// <param name="patternB">The pattern to apply for filtering</param>
/// <param name="allKeys">When true the filter is ommited</param>
/// <param name="cursor">The value of the cursor in the command request</param>
/// <param name="storeCursor">Value of the cursor returned</param>
/// <param name="Keys">The list of keys from the stores</param>
/// <param name="count">The size of the batch of keys</param>
/// <param name="type">Type of key to filter out</param>
/// <returns></returns>
public bool DbScan(ArgSlice patternB, bool allKeys, long cursor, out long storeCursor, out List<byte[]> Keys,  long count = 10, Span<byte> type = default);
  • As a good practice, follow the camel case C# naming convention.

Structure of the Garnet.sln Visual Studio Solution File​

  • Refer to the Code Structure page for details here.

Running the benchmark application​

  • Refer to the Resp benchmark page for details here.

Build​

Test​

As a sanity check, you can run the Garnet test suite. The command to run tests in Release mode, for .NET 8, in shown below (make sure you are in the root folder of the repo).

    dotnet test -c Release -f net8.0 -l "console;verbosity=detailed"

Note that Tsavorite has its own solution file and test suite in the folder <root>/Garnet/libs/storage/Tsavorite.

Tip: By default, Garnet listens to TCP port 3278, you can use this information to adjust your firewall settings if you need to access Garnet from remote machines.