Skip to content

Commit 35a214f

Browse files
bitfasterbitfaster
authored
docs (#239)
1 parent bf2f757 commit 35a214f

File tree

10 files changed

+322
-16
lines changed

10 files changed

+322
-16
lines changed

‎BitFaster.Caching/BitOps.cs‎

Lines changed: 41 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,26 @@
22

33
namespace BitFaster.Caching
44
{
5+
/// <summary>
6+
/// Provides utility methods for bit-twiddling operations.
7+
/// </summary>
58
public class BitOps
69
{
10+
/// <summary>
11+
/// Calculate the smallest power of 2 greater than the input parameter.
12+
/// </summary>
13+
/// <param name="x">The input parameter.</param>
14+
/// <returns>Smallest power of two greater than or equal to x.</returns>
715
public static int CeilingPowerOfTwo(int x)
816
{
917
return (int)CeilingPowerOfTwo((uint)x);
1018
}
1119

20+
/// <summary>
21+
/// Calculate the smallest power of 2 greater than the input parameter.
22+
/// </summary>
23+
/// <param name="x">The input parameter.</param>
24+
/// <returns>Smallest power of two greater than or equal to x.</returns>
1225
public static uint CeilingPowerOfTwo(uint x)
1326
{
1427
#if NETSTANDARD2_0
@@ -26,11 +39,21 @@ public static uint CeilingPowerOfTwo(uint x)
2639

2740
}
2841

42+
/// <summary>
43+
/// Counts the number of 1 bits in the input parameter.
44+
/// </summary>
45+
/// <param name="x">The input parameter.</param>
46+
/// <returns>The number of 1 bits.</returns>
2947
public static int BitCount(int x)
3048
{
3149
return BitCount((uint)x);
3250
}
3351

52+
/// <summary>
53+
/// Counts the number of 1 bits in the input parameter.
54+
/// </summary>
55+
/// <param name="x">The input parameter.</param>
56+
/// <returns>The number of 1 bits.</returns>
3457
public static int BitCount(uint x)
3558
{
3659
#if NETSTANDARD2_0
@@ -47,11 +70,21 @@ public static int BitCount(uint x)
4770
#endif
4871
}
4972

73+
/// <summary>
74+
/// Counts the number of 1 bits in the input parameter.
75+
/// </summary>
76+
/// <param name="x">The input parameter.</param>
77+
/// <returns>The number of 1 bits.</returns>
5078
public static int BitCount(long x)
5179
{
5280
return BitCount((ulong)x);
5381
}
5482

83+
/// <summary>
84+
/// Counts the number of 1 bits in the input parameter.
85+
/// </summary>
86+
/// <param name="x">The input parameter.</param>
87+
/// <returns>The number of 1 bits.</returns>
5588
public static int BitCount(ulong x)
5689
{
5790
#if NETSTANDARD2_0
@@ -68,8 +101,14 @@ public static int BitCount(ulong x)
68101
#endif
69102
}
70103

71-
// Computes Stafford variant 13 of 64-bit mix function.
72-
// http://zimbry.blogspot.com/2011/09/better-bit-mixing-improving-on.html
104+
/// <summary>
105+
/// Computes Stafford variant 13 of 64-bit mix function.
106+
/// </summary>
107+
/// <param name="z">The input parameter.</param>
108+
/// <returns>A bit mix of the input parameter.</returns>
109+
/// <remarks>
110+
/// See http://zimbry.blogspot.com/2011/09/better-bit-mixing-improving-on.html
111+
/// </remarks>
73112
public static ulong Mix64(ulong z)
74113
{
75114
z = (z ^ z >> 30) * 0xbf58476d1ce4e5b9L;

‎BitFaster.Caching/Buffers/MpmcBoundedBuffer.cs‎

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,11 @@ public sealed class MpmcBoundedBuffer<T>
1919
private readonly int slotsMask;
2020
private PaddedHeadAndTail headAndTail; // mutable struct, don't mark readonly
2121

22+
/// <summary>
23+
/// Initializes a new instance of the MpmcBoundedBuffer class with the specified bounded capacity.
24+
/// </summary>
25+
/// <param name="boundedLength">The bounded length.</param>
26+
/// <exception cref="ArgumentOutOfRangeException"></exception>
2227
public MpmcBoundedBuffer(int boundedLength)
2328
{
2429
if (boundedLength < 0)
@@ -54,6 +59,9 @@ public MpmcBoundedBuffer(int boundedLength)
5459
}
5560
}
5661

62+
/// <summary>
63+
/// Gets the number of items contained in the buffer.
64+
/// </summary>
5765
public int Count
5866
{
5967
get
@@ -87,8 +95,16 @@ private int GetCount(int head, int tail)
8795
return 0;
8896
}
8997

98+
/// <summary>
99+
/// The bounded capacity.
100+
/// </summary>
90101
public int Capacity => slots.Length;
91102

103+
/// <summary>
104+
/// Tries to remove an item.
105+
/// </summary>
106+
/// <param name="item">The item to be removed.</param>
107+
/// <returns>A BufferStatus value indicating whether the operation succeeded.</returns>
92108
public BufferStatus TryTake(out T item)
93109
{
94110
// Get the head at which to try to dequeue.
@@ -145,6 +161,11 @@ public BufferStatus TryTake(out T item)
145161
return BufferStatus.Contended;
146162
}
147163

164+
/// <summary>
165+
/// Tries to add the specified item.
166+
/// </summary>
167+
/// <param name="item">The item to be added.</param>
168+
/// <returns>A BufferStatus value indicating whether the operation succeeded.</returns>
148169
public BufferStatus TryAdd(T item)
149170
{
150171
// Get the tail at which to try to return.
@@ -189,7 +210,12 @@ public BufferStatus TryAdd(T item)
189210
return BufferStatus.Contended;
190211
}
191212

192-
// Not thread safe
213+
/// <summary>
214+
/// Removes all values from the buffer.
215+
/// </summary>
216+
/// <remarks>
217+
/// Not thread safe.
218+
/// </remarks>
193219
public void Clear()
194220
{
195221
slots = new Slot[slots.Length];

‎BitFaster.Caching/Buffers/MpscBoundedBuffer.cs‎

Lines changed: 42 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,11 @@ public sealed class MpscBoundedBuffer<T> where T : class
1919
private readonly int mask;
2020
private PaddedHeadAndTail headAndTail; // mutable struct, don't mark readonly
2121

22+
/// <summary>
23+
/// Initializes a new instance of the MpscBoundedBuffer class with the specified bounded capacity.
24+
/// </summary>
25+
/// <param name="boundedLength">The bounded length.</param>
26+
/// <exception cref="ArgumentOutOfRangeException"></exception>
2227
public MpscBoundedBuffer(int boundedLength)
2328
{
2429
if (boundedLength < 0)
@@ -33,8 +38,14 @@ public MpscBoundedBuffer(int boundedLength)
3338
mask = boundedLength - 1;
3439
}
3540

41+
/// <summary>
42+
/// The bounded capacity.
43+
/// </summary>
3644
public int Capacity => buffer.Length;
3745

46+
/// <summary>
47+
/// Gets the number of items contained in the buffer.
48+
/// </summary>
3849
public int Count
3950
{
4051
get
@@ -68,7 +79,14 @@ private int GetCount(int head, int tail)
6879
return 0;
6980
}
7081

71-
// thread safe
82+
/// <summary>
83+
/// Tries to add the specified item.
84+
/// </summary>
85+
/// <param name="item">The item to be added.</param>
86+
/// <returns>A BufferStatus value indicating whether the operation succeeded.</returns>
87+
/// <remarks>
88+
/// Thread safe.
89+
/// </remarks>
7290
public BufferStatus TryAdd(T item)
7391
{
7492
int head = Volatile.Read(ref headAndTail.Head);
@@ -91,7 +109,15 @@ public BufferStatus TryAdd(T item)
91109
return BufferStatus.Contended;
92110
}
93111

94-
// thread safe for single try take/drain + multiple try add
112+
113+
/// <summary>
114+
/// Tries to remove an item.
115+
/// </summary>
116+
/// <param name="item">The item to be removed.</param>
117+
/// <returns>A BufferStatus value indicating whether the operation succeeded.</returns>
118+
/// <remarks>
119+
/// Thread safe for single try take/drain + multiple try add.
120+
/// </remarks>
95121
public BufferStatus TryTake(out T item)
96122
{
97123
int head = Volatile.Read(ref headAndTail.Head);
@@ -119,7 +145,14 @@ public BufferStatus TryTake(out T item)
119145
return BufferStatus.Success;
120146
}
121147

122-
// thread safe for single try take/drain + multiple try add
148+
/// <summary>
149+
/// Drains the buffer into the specified array segment.
150+
/// </summary>
151+
/// <param name="output">The output buffer</param>
152+
/// <returns>The number of items written to the output buffer.</returns>
153+
/// <remarks>
154+
/// Thread safe for single try take/drain + multiple try add.
155+
/// </remarks>
123156
public int DrainTo(ArraySegment<T> output)
124157
{
125158
int head = Volatile.Read(ref headAndTail.Head);
@@ -156,7 +189,12 @@ public int DrainTo(ArraySegment<T> output)
156189
return outCount;
157190
}
158191

159-
// Not thread safe
192+
/// <summary>
193+
/// Removes all values from the buffer.
194+
/// </summary>
195+
/// <remarks>
196+
/// Not thread safe.
197+
/// </remarks>
160198
public void Clear()
161199
{
162200
buffer = new T[buffer.Length];

‎BitFaster.Caching/Buffers/StripedMpmcBuffer.cs‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,20 @@ public sealed class StripedMpmcBuffer<T>
1414

1515
private MpmcBoundedBuffer<T>[] buffers;
1616

17+
/// <summary>
18+
/// Initializes a new instance of the StripedMpmcBuffer class with the specified stripe count and buffer size.
19+
/// </summary>
20+
/// <param name="stripeCount">The stripe count.</param>
21+
/// <param name="bufferSize">The buffer size.</param>
1722
public StripedMpmcBuffer(int stripeCount, int bufferSize)
1823
: this(new StripedBufferSize(bufferSize, stripeCount))
1924
{
2025
}
2126

27+
/// <summary>
28+
/// Initializes a new instance of the StripedMpmcBuffer class with the specified buffer size.
29+
/// </summary>
30+
/// <param name="bufferSize">The buffer size.</param>
2231
public StripedMpmcBuffer(StripedBufferSize bufferSize)
2332
{
2433
buffers = new MpmcBoundedBuffer<T>[bufferSize.StripeCount];
@@ -29,8 +38,19 @@ public StripedMpmcBuffer(StripedBufferSize bufferSize)
2938
}
3039
}
3140

41+
/// <summary>
42+
/// The bounded capacity.
43+
/// </summary>
3244
public int Capacity => buffers.Length * buffers[0].Capacity;
3345

46+
/// <summary>
47+
/// Drains the buffer into the specified output buffer.
48+
/// </summary>
49+
/// <param name="outputBuffer">The output buffer</param>
50+
/// <returns>The number of items written to the output buffer.</returns>
51+
/// <remarks>
52+
/// Thread safe.
53+
/// </remarks>
3454
public int DrainTo(T[] outputBuffer)
3555
{
3656
var count = 0;
@@ -53,6 +73,14 @@ public int DrainTo(T[] outputBuffer)
5373
return count;
5474
}
5575

76+
/// <summary>
77+
/// Tries to add the specified item.
78+
/// </summary>
79+
/// <param name="item">The item to be added.</param>
80+
/// <returns>A BufferStatus value indicating whether the operation succeeded.</returns>
81+
/// <remarks>
82+
/// Thread safe.
83+
/// </remarks>
5684
public BufferStatus TryAdd(T item)
5785
{
5886
var z = BitOps.Mix64((ulong)Environment.CurrentManagedThreadId);
@@ -78,6 +106,12 @@ public BufferStatus TryAdd(T item)
78106
return result;
79107
}
80108

109+
/// <summary>
110+
/// Removes all values from the buffer.
111+
/// </summary>
112+
/// <remarks>
113+
/// Not thread safe.
114+
/// </remarks>
81115
public void Clear()
82116
{
83117
for (var i = 0; i < buffers.Length; i++)

‎BitFaster.Caching/Buffers/StripedMpscBuffer.cs‎

Lines changed: 38 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,13 +15,22 @@ public sealed class StripedMpscBuffer<T> where T : class
1515
{
1616
const int MaxAttempts = 3;
1717

18-
private MpscBoundedBuffer<T>[] buffers;
18+
private readonly MpscBoundedBuffer<T>[] buffers;
1919

20+
/// <summary>
21+
/// Initializes a new instance of the StripedMpscBuffer class with the specified stripe count and buffer size.
22+
/// </summary>
23+
/// <param name="stripeCount">The stripe count.</param>
24+
/// <param name="bufferSize">The buffer size.</param>
2025
public StripedMpscBuffer(int stripeCount, int bufferSize)
2126
: this(new StripedBufferSize(bufferSize, stripeCount))
2227
{
2328
}
2429

30+
/// <summary>
31+
/// Initializes a new instance of the StripedMpscBuffer class with the specified buffer size.
32+
/// </summary>
33+
/// <param name="bufferSize">The buffer size.</param>
2534
public StripedMpscBuffer(StripedBufferSize bufferSize)
2635
{
2736
buffers = new MpscBoundedBuffer<T>[bufferSize.StripeCount];
@@ -32,10 +41,24 @@ public StripedMpscBuffer(StripedBufferSize bufferSize)
3241
}
3342
}
3443

44+
/// <summary>
45+
/// Gets the number of items contained in the buffer.
46+
/// </summary>
3547
public int Count => buffers.Sum(b => b.Count);
3648

49+
/// <summary>
50+
/// The bounded capacity.
51+
/// </summary>
3752
public int Capacity => buffers.Length * buffers[0].Capacity;
3853

54+
/// <summary>
55+
/// Drains the buffer into the specified array segment.
56+
/// </summary>
57+
/// <param name="outputBuffer">The output buffer</param>
58+
/// <returns>The number of items written to the output buffer.</returns>
59+
/// <remarks>
60+
/// Thread safe for single try take/drain + multiple try add.
61+
/// </remarks>
3962
public int DrainTo(T[] outputBuffer)
4063
{
4164
var count = 0;
@@ -54,6 +77,14 @@ public int DrainTo(T[] outputBuffer)
5477
return count;
5578
}
5679

80+
/// <summary>
81+
/// Tries to add the specified item.
82+
/// </summary>
83+
/// <param name="item">The item to be added.</param>
84+
/// <returns>A BufferStatus value indicating whether the operation succeeded.</returns>
85+
/// <remarks>
86+
/// Thread safe.
87+
/// </remarks>
5788
public BufferStatus TryAdd(T item)
5889
{
5990
var z = BitOps.Mix64((ulong)Environment.CurrentManagedThreadId);
@@ -79,6 +110,12 @@ public BufferStatus TryAdd(T item)
79110
return result;
80111
}
81112

113+
/// <summary>
114+
/// Removes all values from the buffer.
115+
/// </summary>
116+
/// <remarks>
117+
/// Not thread safe.
118+
/// </remarks>
82119
public void Clear()
83120
{
84121
for (var i = 0; i < buffers.Length; i++)

0 commit comments

Comments
 (0)