[API Proposal]: XXH3

[stephentoub]

Background and motivation

System.IO.Hashing contains implementations of a variety of non-cryptographic hash algorithms, including several from the xxHash family. In particular, it currently includes implementations of XXH32 and XXH64, but not XXH3 nor XXH128. The latter two are vectorizable, with XXH3 clocking in as the fastest of the family, in particular on smaller data.

https://github.com/Cyan4973/xxHash

API Proposal

Exact same shape as the existing XxHash32 and XxHash64, just with a different name.

namespace System.IO.Hashing;

public sealed partial class XxHash3 : NonCryptographicHashAlgorithm
{
    public XxHash3();
    public XxHash3(int seed);

    public static byte[] Hash(byte[] source);
    public static byte[] Hash(byte[] source, int seed);
    public static byte[] Hash(ReadOnlySpan<byte> source, int seed = 0);
    public static int Hash(ReadOnlySpan<byte> source, Span<byte> destination, int seed = 0);
    public static bool TryHash(ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten, int seed = 0);
}

We could also consider adding XxHash128.

API Usage

int bytesWritten = XxHash3.Hash(source, destination);

Alternative Designs

• We chose to name the XXH32 and XXH64 classes XxHash32 and XxHash64. Feels strange to name the XXH3 class XxHash3, but that would seem to follow the pattern we established. Alternatively, it could just be XXH3.

Risks

No response

[ghost]

Tagging subscribers to this area: @dotnet/area-system-io
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

System.IO.Hashing contains implementations of a variety of non-cryptographic hash algorithms, including several from the xxHash family. In particular, it currently includes implementations of XXH32 and XXH64, but not XXH3 nor XXH128. The latter two are vectorizable, with XXH3 clocking in as the fastest of the family, in particular on smaller data.

https://github.com/Cyan4973/xxHash

API Proposal

Exact same shape as the existing XxHash32 and XxHash64, just with a different name.

namespace System.IO.Hashing;

public sealed partial class XxHash3 : NonCryptographicHashAlgorithm
{
    public XxHash3();
    public XxHash3(int seed);

    public static byte[] Hash(byte[] source);
    public static byte[] Hash(byte[] source, int seed);
    public static byte[] Hash(ReadOnlySpan<byte> source, int seed = 0);
    public static int Hash(ReadOnlySpan<byte> source, Span<byte> destination, int seed = 0);
    public static bool TryHash(ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten, int seed = 0);
}

We could also consider adding XxHash128.

API Usage

int bytesWritten = XxHash3.Hash(source, destination);

Alternative Designs

• We chose to name the XXH32 and XXH64 classes XxHash32 and XxHash64. Feels strange to name the XXH3 class XxHash3, but that would seem to follow the pattern we established. Alternatively, it could just be XXH3.

Risks

No response

Author:	stephentoub
Assignees:	-
Labels:	api-suggestion, area-System.IO
Milestone:	8.0.0

[stephentoub]

cc: @bartonjs

[ghost]

Tagging subscribers to this area: @dotnet/area-system-security, @vcsjones
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

System.IO.Hashing contains implementations of a variety of non-cryptographic hash algorithms, including several from the xxHash family. In particular, it currently includes implementations of XXH32 and XXH64, but not XXH3 nor XXH128. The latter two are vectorizable, with XXH3 clocking in as the fastest of the family, in particular on smaller data.

https://github.com/Cyan4973/xxHash

API Proposal

Exact same shape as the existing XxHash32 and XxHash64, just with a different name.

namespace System.IO.Hashing;

public sealed partial class XxHash3 : NonCryptographicHashAlgorithm
{
    public XxHash3();
    public XxHash3(int seed);

    public static byte[] Hash(byte[] source);
    public static byte[] Hash(byte[] source, int seed);
    public static byte[] Hash(ReadOnlySpan<byte> source, int seed = 0);
    public static int Hash(ReadOnlySpan<byte> source, Span<byte> destination, int seed = 0);
    public static bool TryHash(ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten, int seed = 0);
}

We could also consider adding XxHash128.

API Usage

int bytesWritten = XxHash3.Hash(source, destination);

Alternative Designs

• We chose to name the XXH32 and XXH64 classes XxHash32 and XxHash64. Feels strange to name the XXH3 class XxHash3, but that would seem to follow the pattern we established. Alternatively, it could just be XXH3.

Risks

No response

Author:	stephentoub
Assignees:	-
Labels:	area-System.Security, api-ready-for-review
Milestone:	8.0.0

[terrajobst]

Video

• Looks good as proposed
  • We considered also adding XxHash128 but decided to wait until there is a need.

namespace System.IO.Hashing;

public sealed partial class XxHash3 : NonCryptographicHashAlgorithm
{
    public XxHash3();
    public XxHash3(int seed);

    public static byte[] Hash(byte[] source);
    public static byte[] Hash(byte[] source, int seed);
    public static byte[] Hash(ReadOnlySpan<byte> source, int seed = 0);
    public static int Hash(ReadOnlySpan<byte> source, Span<byte> destination, int seed = 0);
    public static bool TryHash(ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten, int seed = 0);
}

[xoofx]

Hey,

We considered also adding XxHash128 but decided to wait until there is a need.

I have a need for 128 bits support, mainly for content addressable storage. I would gladly try to bring support for it.

Do I need to open a separate issue for a XxHash128 API proposal (which would be a copy paste of the XxHash3)?

[krwq]

@xoofx yes please open a separate issue with API proposal (make sure to describe your scenario)