#pragma once

#include "internal.h"

class CRingBuffer

{

private:

//

// Private local variables.

//

//

// The size in bytes of the ring buffer.

//

SIZE_T m_Size;

//

// A pointer to the base of the ring buffer.

//

PBYTE m_Base;

//

// A pointer to the byte beyond the end of the ring buffer. Used for

// quick comparisons when determining if we need to wrap.

//

PBYTE m_End;

//

// A pointer to the current read point in the ring buffer.

//

// Updates to this are not protected by any lock. This is different from

// the write pointer, which is protected by the "pending read pointer"

// lock. The reason for this difference is that in this driver, we do not

// keep write requests pending. If there is not enough space to write all

// the data that was requested, we write as much as we can and drop the

// rest (lossy data transfer).

//

// If we had multiple threads modifying this pointer, then that would

// provide yet another reason for protecting updates to the pointer using a

// lock. However, in this driver, at any given time we have only one thread

// that modifies this pointer (the thread that runs the read callback).

// This is true because we use a sequential queue for read requests. If we

// were to change our read queue to be a parallel queue, this would no

// longer be true.

//

//

PBYTE m_Head;

//

// A pointer to the current write point in the ring buffer.

//

// Updates to this pointer are protected by the "pending read pointer

// lock", because we do not want a consumer thread to mark a read request

// as pending while we are in the process of writing data to the buffer.

// The reason is that the write that we are currently performing might

// actually supply enough data to satisfy the read request, in which case

// it should not be marked pending at all.

// If the read request were to be marked pending in the situation described

// above, then we would need some trigger to later retrieve the request and

// complete it. In our driver, arrival of data is the only event that can

// trigger this. So if no more data arrives, the request will remain

// pending forever, even though there is enough data in the buffer to

// complete it. Hence we do not keep a read request pending in situations

// where the read buffer contains enough data to satisfy it.

//

// If we had multiple threads modifying this pointer, then that would

// provide yet another reason for protecting updates to the pointer using a

// lock. However, in this driver, at any given time we have only one thread

// that modifies this pointer (the thread that runs the write callback).

// This is true because we use a sequential queue for write requests. If we

// were to change our write queue to be a parallel queue, this would no

// longer be true.

//

PBYTE m_Tail;

private:

//

// Private Internal Methods.

//

void

GetAvailableSpace(

_Out_ SIZE_T *AvailableSpace

)

{

WUDF_TEST_DRIVER_ASSERT(AvailableSpace);

PBYTE headSnapshot = NULL;

PBYTE tailSnapshot = NULL;

PBYTE tailPlusOne = NULL;

//

// Take a snapshot of the head and tail pointers. We will compute the

// available space based on this snapshot. This is safe to do in a

// single-producer, single-consumer model, because -

// * A producer will call GetAvailableSpace() to determine whether

// there is enough space to write the data it is trying to write.

// The only other thread that could modify the amount of space

// available is the consumer thread, which can only increase the

// amount of space available. Hence it is safe for the producer

// to write based on this snapshot.

// * A consumer thread will call GetAvailableSpace() to determine

// whether there is enough data in the buffer for it to read.

// (Available data = Buffer size - Available space). The only

// other thread that could modify the amount of space available

// is the producer thread, which can only decrease the amount of

// space available (thereby increasing the amount of data

// available. Hence it is safe for the consumer to read based on

// this snapshot.

//

headSnapshot = m_Head;

tailSnapshot = m_Tail;

//

// In order to distinguish between a full buffer and an empty buffer,

// we always leave the last byte of the buffer unused. So, an empty

// buffer is denoted by -

// tail == head

// ... and a full buffer is denoted by -

// (tail+1) == head

//

tailPlusOne = ((tailSnapshot+1) == m_End) ? m_Base : (tailSnapshot+1);

if (tailPlusOne == headSnapshot)

{

//

// Buffer full

//

*AvailableSpace = 0;

}

else if (tailSnapshot == headSnapshot)

{

//

// Buffer empty

// The -1 in the computation below is to account for the fact that

// we always leave the last byte of the ring buffer unused in order

// to distinguish between an empty buffer and a full buffer.

//

*AvailableSpace = m_Size - 1;

}

else

{

if (tailSnapshot > headSnapshot)

{

//

// Data has not wrapped around the end of the buffer

// The -1 in the computation below is to account for the fact

// that we always leave the last byte of the ring buffer unused

// in order to distinguish between an empty buffer and a full

// buffer.

//

*AvailableSpace = m_Size - (tailSnapshot - headSnapshot) - 1;

}

else

{

//

// Data has wrapped around the end of the buffer

// The -1 in the computation below is to account for the fact

// that we always leave the last byte of the ring buffer unused

// in order to distinguish between an empty buffer and a full

// buffer.

//

*AvailableSpace = (headSnapshot - tailSnapshot) - 1;

}

}

return;

}

public:

//

// Public Internal methods.

//

CRingBuffer(

VOID

);

~CRingBuffer(

VOID

);

HRESULT

Initialize(

_In_ SIZE_T BufferSize

);

HRESULT

Write(

_In_reads_bytes_(DataSize) PBYTE Data,

_In_ SIZE_T DataSize

);

HRESULT

Read(

_Out_writes_bytes_to_(DataSize, *BytesCopied) PBYTE Data,

_In_ SIZE_T DataSize,

_Out_ SIZE_T *BytesCopied

);

void

GetAvailableData(

_Out_ SIZE_T *AvailableData

)

{

SIZE_T availableSpace;

WUDF_TEST_DRIVER_ASSERT(AvailableData);

GetAvailableSpace(&availableSpace);

//

// The -1 in the arithmetic below accounts for the fact that we always

// keep 1 byte of the ring buffer unused in order to distinguish

// between a full buffer and an empty buffer.

//

*AvailableData = m_Size - availableSpace - 1;

return;

}

};