Skip to content

Commit

Permalink
Extend 'file_stream<>' documentation comments to 100
Browse files Browse the repository at this point in the history
  • Loading branch information
@SSoelvsten
SSoelvsten committed Jun 22, 2024
1 parent 9d68b28 commit c508cf5
Showing 1 changed file with 56 additions and 60 deletions.
116 changes: 56 additions & 60 deletions src/adiar/internal/io/file_stream.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,96 +10,95 @@

namespace adiar::internal
{
//////////////////////////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////////////////////////////////////////////
/// \brief Stream to a file with a one-way reading direction.
///
/// \tparam T The type of the file's elements
///
/// \tparam Reverse Whether the reading direction should be reversed
//////////////////////////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////////////////////////////////////////////
template <typename T, bool Reverse = false>
class file_stream
{
public:
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
/// \brief Type of the file's elements.
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
using value_type = T;

public:
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
static size_t
memory_usage()
{
return tpie::file_stream<value_type>::memory_usage();
}

private:
////////////////////////////////////////////////////////////////////////////
/// \brief Buffer of a single element, since TPIE does not support a
/// `peek_back` function yet (TPIE Issue #187).
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
/// \brief Buffer of a single element, since TPIE does not support a `peek_back` function yet
/// (TPIE Issue #187).
////////////////////////////////////////////////////////////////////////////////////////////////
mutable value_type _peeked;

////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
/// \brief Whether an \em unpulled element is stored in `_peeked`.
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
mutable bool _has_peeked = false;

////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
/// \brief Whether elements should be \em negated on-the-fly.
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
bool _negate = false;

////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
/// \brief TPIE's file stream object to read the file with.
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
mutable typename tpie::file_stream<value_type> _stream;

////////////////////////////////////////////////////////////////////////////
/// \brief If attached to a shared file then hook into the reference
/// counting such that the file is not garbage collected while we
/// read from it.
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
/// \brief If attached to a shared file then hook into the reference counting such that the file
/// is not garbage collected while we read from it.
////////////////////////////////////////////////////////////////////////////////////////////////
shared_ptr<void> _file_ptr;

public:
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
/// \brief Construct unattached to any file.
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
file_stream()
{}

////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
file_stream(const file_stream<value_type, Reverse>&) = delete;
file_stream(file_stream<value_type, Reverse>&&) = delete;

////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
/// \brief Construct attached to a given shared `file<value_type>`.
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
file_stream(const file<value_type>& f, bool negate = false)
{
attach(f, negate);
}

////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
/// \brief Construct attached to a given shared `file<value_type>`.
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
file_stream(const adiar::shared_ptr<file<value_type>>& f, bool negate = false)
{
attach(f, negate);
}

////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
/// \brief Detaches and cleans up when destructed.
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
~file_stream()
{
detach();
}

protected:
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
void
attach(const file<value_type>& f, const adiar::shared_ptr<void>& shared_ptr, bool negate)
{
Expand All @@ -109,8 +108,8 @@ namespace adiar::internal
// Hook into reference counting.
_file_ptr = shared_ptr;

// Touch the file to make sure it exists on disk. Since 'f' is const, use
// the private '__touch()' member function instead.
// Touch the file to make sure it exists on disk. Since 'f' is const, use the private
// '__touch()' member function instead.
f.__touch();

// Open the stream to the file
Expand All @@ -121,57 +120,56 @@ namespace adiar::internal
_negate = negate;
}

////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
// Befriend the few places that need direct access to the above 'attach'.
template <typename tparam__elem_t, bool tparam__Reverse>
friend class levelized_file_stream;

public:
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
/// \brief Attach to a file.
///
/// \pre No `file_writer` is currently attached to this file.
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
void
attach(const file<value_type>& f, bool negate = false)
{
attach(f, nullptr, negate);
}

////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
/// \brief Attach to a shared file.
///
/// \pre No `file_writer` is currently attached to this file.
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
void
attach(const adiar::shared_ptr<file<value_type>>& f, bool negate = false)
{
attach(*f, f, negate);
}

////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
/// \brief Whether the reader is currently attached.
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
bool
attached() const
{
return _stream.is_open();
}

////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
/// \brief Detach from the file, i.e. close the stream.
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
void
detach()
{
_stream.close();
if (_file_ptr) { _file_ptr.reset(); }
}

////////////////////////////////////////////////////////////////////////////
/// \brief Reset the read head back to the beginning (relatively to the
/// reading direction).
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
/// \brief Reset the read head back to the beginning (relatively to the reading direction).
////////////////////////////////////////////////////////////////////////////////////////////////
void
reset()
{
Expand All @@ -183,7 +181,7 @@ namespace adiar::internal
}

private:
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
bool
__can_read() const
{
Expand All @@ -195,17 +193,17 @@ namespace adiar::internal
}

public:
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
/// \brief Whether the stream contains more elements.
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
bool
can_pull() const
{
return _has_peeked || __can_read();
}

private:
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
const value_type
__read()
{
Expand All @@ -219,11 +217,11 @@ namespace adiar::internal
}

public:
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
/// \brief Obtain the next element (and move the read head).
///
/// \pre `can_pull() == true`.
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
const value_type
pull()
{
Expand All @@ -236,11 +234,11 @@ namespace adiar::internal
}

public:
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
/// \brief Obtain the next element (but do not move the read head)
///
/// \pre `can_pull() == true`.
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
const value_type
peek()
{
Expand All @@ -253,21 +251,19 @@ namespace adiar::internal
}

public:
////////////////////////////////////////////////////////////////////////////
/// \brief Obtain the next element that is greater than or equal to the
/// given target value.
////////////////////////////////////////////////////////////////////////////////////////////////
/// \brief Obtain the next element that is greater than or equal to the given target value.
///
/// \param s The value to seek for
///
/// \pre The content is in ascending order and `can_pull() == true`.
////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////
template <typename seek_t = value_type>
const value_type
seek(seek_t tgt)
{
// Notice, the peek() also changes the state of '_peeked' and
// '_has_peeked'. This initializes the invariant for 'seek' that '_peeked'
// is the "current position".
// Notice, the peek() also changes the state of '_peeked' and '_has_peeked'. This initializes
// the invariant for 'seek' that '_peeked' is the "current position".
if (tgt < peek()) { return _peeked; }

// Only move to "next value", if there is more to pull.
Expand Down

0 comments on commit c508cf5

Please sign in to comment.