From ba885f324311fcb0b0d98acd642ed0524dbd3da2 Mon Sep 17 00:00:00 2001
From: Doralitze <doralitze@chaotikum.org>
Date: Sat, 7 Aug 2021 19:51:29 +0200
Subject: [PATCH] add: Documentation for non-trivial auto_fd methods
---
src/net/async_fd.hpp | 62 +++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 61 insertions(+), 1 deletion(-)
diff --git a/src/net/async_fd.hpp b/src/net/async_fd.hpp
index 42c7fe0..83bfedd 100644
--- a/src/net/async_fd.hpp
+++ b/src/net/async_fd.hpp
@@ -4,6 +4,13 @@
namespace rmrf::net {
+ /**
+ * @class null_fd
+ * @author leondietrich
+ * @date 07/08/21
+ * @file async_fd.hpp
+ * @brief Null ptr file descriptor dummy class
+ */
class null_fd {
public:
constexpr explicit null_fd() {}
@@ -11,8 +18,22 @@ namespace rmrf::net {
constexpr operator int() const { return -1; }
};
+ /**
+ * Instantiate a null FD.
+ */
constexpr null_fd nullfd{};
+ /**
+ * Automatic file descriptor.
+ *
+ * This class wraps raw file descriptors and handles their life time.
+ *
+ * @class auto_fd
+ * @author leondietrich
+ * @date 07/08/21
+ * @file async_fd.hpp
+ * @brief A file descriptor with smart (automatic) resource handling.
+ */
class auto_fd {
private:
int _fd;
@@ -23,6 +44,7 @@ namespace rmrf::net {
explicit inline auto_fd(int fd) noexcept : _fd {fd} {}
inline auto_fd(auto_fd &&fd) noexcept : _fd {fd.release()} {}
+
inline auto_fd &operator=(auto_fd &&fd) noexcept {
reset(fd.release());
return *this;
@@ -31,20 +53,45 @@ namespace rmrf::net {
auto_fd(const auto_fd &) = delete;
auto_fd &operator=(const auto_fd &) = delete;
+ /**
+ * @brief This deconstructor frees (closes) the associated resource.
+ */
inline ~auto_fd() noexcept {
reset();
}
+ /**
+ * Use this method to obtain a raw file descriptor for usage with lower level APIs.
+ * Calling this method won't invalidate the auto_fd. Don't keep this value around
+ * (for immediate consumption only).
+ * @brief Get the raw representation of the file descriptor for interaction with kernel APIs.
+ * @return A raw file descriptor
+ */
inline int get() const noexcept { return _fd; }
+ /**
+ * Use this method in order to obtain a raw file descriptor from this auto_fd.
+ * Calling this method will invalidate the auto_fd object. Deleting the auto_fd
+ * after having called this method won't close the associated resource.
+ * Try to avoid this method as handling raw file descriptors is way more error
+ * prone than handling auto_fd.
+ * @brief Get raw file descriptor for kernel APIs and cease control over it
+ * @return The raw file descriptor
+ */
int release() noexcept {
int r(_fd);
_fd = -1;
return r;
}
- // Close an open file descriptor. Reset the descriptor to -1.
+ /**
+ * Use this method in order to manually close the resource associated with this file descriptor.
+ * After this method was executed this file descriptor is invalid. Further calls to this method
+ * won't do anything.
+ * @brief close the file descriptor
+ */
inline void close() noexcept {
+ // Close an open file descriptor. Reset the descriptor to -1.
if (_fd >= 0) {
::close(_fd);
@@ -53,6 +100,12 @@ namespace rmrf::net {
}
}
+ /**
+ * Use this method in order to reset the file descriptor to a new one.
+ * If the original file descriptor was in a valid state it will be closed.
+ * @brief Reset the auto_fd object to the given raw file descriptor.
+ * @param fd The new file descriptor to use.
+ */
inline void reset(int fd = -1) noexcept {
if (_fd >= 0) {
close(); // Don't check for an error as not much we can do here.
@@ -61,6 +114,13 @@ namespace rmrf::net {
_fd = fd;
}
+ /**
+ * Use this method in order to check if the file descriptor is still valid.
+ * If the file descriptor has already been closed or is the nullfd this
+ * method will return false.
+ * @brief Check if the file descriptor is valid.
+ * @return true if the file descriptor is still valid or otherwise false.
+ */
inline bool valid() const {
return _fd >= 0;
}
--
GitLab