Typically, a file system in a game engine comes with all the bells and whistles like multiple file devices, support for zipped files, encryption, device aliases, asynchronous I/O, and more. But buried underneath every file system lives a low-level implementation (directly using OS/SDK functions), which in turn is used in the high-level file system.

This low-level implementation should be the only platform-specific file implementation in the whole file system, and is the topic of today’s post.

In the Molecule Engine, the low-level file implementation is called OsFile, and handles both synchronous and asynchronous requests.

The synchronous part of the API is pretty straightforward:

class OsFile
{
public:
  OsFile(const char* path, FileSystem::Mode mode, bool async);
  ~OsFile(void);

  ////////////////////////////////////////////////////////////////////////
  // Synchronous API
  ////////////////////////////////////////////////////////////////////////

  /// Synchronously reads from the file into a buffer. Returns the number of bytes read, or 0 if the operation failed.
  size_t Read(void* buffer, size_t length);

  /// Synchronously writes from a buffer into the file. Returns the number of bytes written, or 0 if the operation failed.
  size_t Write(const void* buffer, size_t length);

  /// Seeks to the desired position
  void Seek(size_t position);

  /// Seeks to the end of the file
  void SeekToEnd(void);

  /// Skips a certain amount of bytes
  void Skip(size_t bytes);

  /// Returns the current position in the file, or INVALID_SET_FILE_POINTER (0xFFFFFFFF) if the operation failed.
  size_t Tell(void) const;

  ////////////////////////////////////////////////////////////////////////
  // Asynchronous API
  ////////////////////////////////////////////////////////////////////////

  [...]
};

I choose not to use or expose FILE_BEGIN, FILE_CURRENT and FILE_END (used for seeking) in the API itself – it’s used internally, but the user shouldn’t have to bother with it. It’s just a relict of the olden days of real stream-based devices anyway, and that’s the reason why Seek(), SeekToEnd() and Skip() exist. Other than that, the synchronous part of the API just does what it says on the tin.

What about the asynchronous API? One solution I have seen in the past was something like the following:

class OsFile
{
public:
  [...]

  ////////////////////////////////////////////////////////////////////////
  // Asynchronous API
  ////////////////////////////////////////////////////////////////////////

  /// Asynchronously reads from the file into a buffer
  void ReadAsync(void* buffer, size_t length);

  /// Asynchronously writes from a buffer into the file
  void WriteAsync(const void* buffer, size_t length);

  /// Waits until the asynchronous operation has finished
  void WaitForAsync(void);

  /// Returns the number of bytes transferred in the asynchronous operation
  size_t GetAsyncBytesTransferred(void) const;
};

Unfortunately, this solution has a serious flaw: You can never initiate more than one asynchronous operation at the same time, because otherwise the calls to WaitForAsync() and GetAsyncBytesTransferred() would be ambiguous. With asynchronous I/O you can never be sure which I/O finished first, hence something like the following won’t work:

OsFile* file = [...];
file->ReadAsync(header, 256);
file->ReadAsync(data, 65536);
file->WaitForAsync(); // which one finished?

Part of the reason for using asynchronous I/O is that you can overlap read and write operations, and do several asynchronous operations at once. I’ve worked with sound middleware which explicitly used those features, and integrating it into the above system was not nice. Hence, let’s strive for something different.

An alternative, better solution would be something like the following:

class OsFile
{
public:
  [...]

  AsyncOperation* ReadAsync(void* buffer, size_t length);

  AsyncOperation* WriteAsync(const void* buffer, size_t length);

  void WaitForAsync(AsyncOperation* operation);

  size_t GetAsyncBytesTransferred(AsyncOperation* operation) const;
};

By returning a unique AsyncOperation instance, the API can use that as an identifier/token for the corresponding, internal asynchronous operation, so multiple reads/writes now work:

OsFile* file = [...];
AsyncOperation* op1 = file->ReadAsync(header, 256);
AsyncOperation* op2 = file->ReadAsync(data, 65536);
file->WaitForAsync(op1);
// header has been read at this point, data reading still carries on

But still, there is a minor quirk in this design:

• Ownership of the AsyncOperation instances is transferred to the user, meaning that each AsyncOperation has to be delete‘d manually at the calling site, which is error-prone.

Keeping that in mind, the design I use in the Molecule Engine is the following:

class OsFile
{
public:
  [...]

  /// Asynchronously reads from the file into a buffer
  OsAsyncFileOperation ReadAsync(void* buffer, size_t length, size_t position);

  /// Asynchronously writes from a buffer into the file
  OsAsyncFileOperation WriteAsync(const void* buffer, size_t length, size_t position);
};

As you can see, waiting for an operation and getting the amount of transferred bytes is no longer part of the OsFile API. Instead, OsAsyncFileOperation is a self-contained object which keeps track of the asynchronous operation internally, and offers the following API:

class OsAsyncFileOperation
{
public:
  OsAsyncFileOperation(HANDLE file, size_t position);
  OsAsyncFileOperation(const OsAsyncFileOperation& other);
  OsAsyncFileOperation& operator=(const OsAsyncFileOperation& other);
  ~OsAsyncFileOperation(void);

  /// Returns whether or not the asynchronous operation has finished
  bool HasFinished(void) const;

  /// Waits until the asynchronous operation has finished. Returns the number of transferred bytes.
  size_t WaitUntilFinished(void) const;

  /// Cancels the asynchronous operation
  void Cancel(void);

private:
  HANDLE m_file;
  ReferenceCountedItem<OVERLAPPED>* m_overlapped;
};

Because OsAsyncFileOperation stores a reference-counted object internally, it can be copied, assigned, and stored somewhere. The copy-constructor and assignment operator increase m_overlapped‘s referece count, and the destructor delete‘s m_overlapped if its reference count reaches zero:

OsAsyncFileOperation::OsAsyncFileOperation(const OsAsyncFileOperation& other)
  : m_file(other.m_file)
  , m_overlapped(other.m_overlapped)
{
  m_overlapped->AddReference();
}

OsAsyncFileOperation& OsAsyncFileOperation::operator=(const OsAsyncFileOperation& other)
{
  if (this != &other)
  {
    m_file = other.m_file;
    m_overlapped = other.m_overlapped;
    m_overlapped->AddReference();
  }

  return *this;
}

OsAsyncFileOperation::~OsAsyncFileOperation(void)
{
  if (m_overlapped->RemoveReference() == 0)
    delete m_overlapped;
}

This API allows for simultaneous asynchronous reads/writes, and is completely non-ambiguous to use:

void Store(const OsAsyncFileOperation& op)
{
  // hold on to operation somehow
}

OsFile* file = [...];
OsAsyncFileOperation op1 = file->ReadAsync(header, 256);
OsAsyncFileOperation op2 = file->ReadAsync(data, 65536);
const size_t headerRead = op1.WaitUntilFinished();
// whenever op1 and op2 go out of scope, the internal object will be automatically deleted
// and still, the following would work too:
Store(op);

In the next installment of the series, we will see how the high-level file system makes use of the low-level OsFile.