randolf.ca  1.00
Randolf Richardson's C++ classes
Loading...
Searching...
No Matches
rsocket_io
1#pragma once
2
3#include <mutex> // std::mutex
4
5namespace randolf {
6
7 /*======================================================================*//**
8 @brief
9 Structure of socket I/O statistics tracked by rsocket.
10 The reason this is a subclass of @c std::mutex is to ensure a thread-safe
11 operation for the @c rsocket::~rsocket destructor when making a final copy of
12 the internally-tracked I/O statistics using the pointer to this structure (if
13 specified with the @ref rsocket::net_io_final() method).
14
15 @note
16 To find out the total overall bytes received/transmitted, the sum of @ref
17 bytes_rx and @ref crypt_rx, the sum of @ref bytes_sx and @ref crypt_sx, and
18 the sum of @ref bytes_tx and @ref crypt_tx will provide this statistical
19 information:
20 @code{.cpp}
21 #include <randolf/rsocket>
22
23 std::unique_ptr<randolf::rsocket_io> io = r.net_io();
24 __uint128_t total_rx = io->bytes_rx // Bytes received (unencrypted)
25 + io->crypt_rx; // Bytes received (encrypted)
26 __uint128_t total_sx = io->bytes_sx // Spare bytes received (unencrypted)
27 + io->crypt_sx; // Spare bytes received (encrypted)
28 __uint128_t total_tx = io->bytes_tx // Bytes transmitted (unencrypted)
29 + io->crypt_tx; // Bytes transmitted (encrypted)
30 @endcode
31 When data is buffered (buffering is triggered by the @ref rsocket::recvline()
32 method), there may be occasions where data is spared (left behind), which is
33 tracked in the @ref bytes_sx and @ref crypt_sx values. These values can be
34 subtracted from the totals, if need be, as follows:
35 @code{.cpp}
36 #include <randolf/rsocket>
37
38 std::unique_ptr<randolf::rsocket_io> io = r.net_io();
39 __uint128_t total_rx = io->bytes_rx // Bytes received (unencrypted)
40 + io->crypt_rx // Bytes received (encrypted)
41 - io->bytes_sx // Bytes received (unencrypted spare)
42 - io->crypt_sx; // Bytes received (encrypted spare)
43 __uint128_t total_tx = io->bytes_tx // Bytes transmitted (unencrypted)
44 + io->crypt_tx; // Bytes transmitted (encrypted)
45 @endcode
46 Spare bytes are only applicable to received data statistics because buffering
47 is only used to receive data.
48
49 This statistical data is typically used in logging, and also in applications
50 that keep track of I/O on a per-user basis.
51 @author Randolf Richardson
52 @version 1.00
53 @par History
54 - 2023-Apr-30 v1.00 Initial version
55 @see rsocket::net_io()
56 @see rsocket::net_io(const char*, size_t, rsocket_io*)
57 @see rsocket::net_io_final()
58 @see rsocket::net_io_update()
59 *///=========================================================================
60 struct rsocket_io : public std::mutex {
61
62 /*======================================================================*//**
63 @brief
64 Total number of unencrypted bytes received.
65 *///=========================================================================
66 __uint128_t bytes_rx;
67
68 /*======================================================================*//**
69 @brief
70 Total number of unencrypted bytes spared (received, and remains in buffer).
71 *///=========================================================================
72 __uint128_t bytes_sx;
73
74 /*======================================================================*//**
75 @brief
76 Total number of unencrypted bytes transmitted.
77 *///=========================================================================
78 __uint128_t bytes_tx;
79
80 /*======================================================================*//**
81 @brief
82 Total number of encrypted bytes received.
83 *///=========================================================================
84 __uint128_t crypt_rx;
85
86 /*======================================================================*//**
87 @brief
88 Total number of encrypted bytes spared (received, and remains in buffer).
89 *///=========================================================================
90 __uint128_t crypt_sx;
91
92 /*======================================================================*//**
93 @brief
94 Total number of encrypted bytes transmitted.
95 *///=========================================================================
96 __uint128_t crypt_tx;
97
98 /*======================================================================*//**
99 @brief
100 Should always be initialized to FALSE; reserved for the @c rsocket::~rsocket
101 destructor to set to TRUE.
102 @see rsocket::~rsocket()
103 *///=========================================================================
104 bool is_final;
105
106 }; // -x- struct rsocket_io -x-
107
108}; // -x- namespace randolf -x-