FC++  v0.7.2-1128
FileCatalyst Fast File Transfers - C++ Library
fc::TransferStats Class Reference

File transfer statistics. More...

#include <FCTransferStats.hpp>

Collaboration diagram for fc::TransferStats:

Public Types

enum  EState {
  kInvalid = -1,
  kUnknown = 0,
  kMd5InProgress = 10,
  kMd5Success,
  kMd5Failed,
  kMd5Skipped,
  kPending = 20,
  kTransferStarted,
  kTransferFinished,
  kTransferFailed,
  kFull = 30,
  kPartial,
  kSkippedMD5,
  kSkippedFileExists
}
 Used in several locations to indicate the state of the file transfer. More...
 

Public Member Functions

 TransferStats (void)
 Constructor. More...
 
TransferStatsclear (const bool all=true)
 Clear most or all of the transfer statistics. More...
 
TransferStatsoperator+= (const TransferStats &rhs)
 Combine transfer statistics to get statistics over several files. More...
 
fc::StrMap getMap (const std::string &header="") const
 Format all the transfer statistics as easy-to-read text strings, and store into a map of strings. More...
 
std::string getStr (const std::string &header="", const bool all=false) const
 Similar to getMap(), but append all items to create a single multi-line text string to display for debug purposes. More...
 
fc::StrMapadd_to_map (fc::StrMap &m, const std::string &header="") const
 Get the map entries – similar to getmap() – but instead of returning a new map, add the entries to a pre-existing map. More...
 
fc::Local target_local_filename (void) const
 Returns the local filename which should be used. More...
 
fc::Remote target_remote_filename (void) const
 Returns the remote filename which should be used. More...
 
bool tmp_filename_is_disabled (void) const
 Determine if this file stats object has the necessary filename information to use a temporary filename during transfer. More...
 
bool tmp_filename_is_enabled (void) const
 Determine if this file stats object has the necessary filename information to use a temporary filename during transfer. More...
 

Public Attributes

EState md5
 State of the MD5 verification. More...
 
EState transfer
 State of the file transfer. More...
 
EState type
 The type of transfer. More...
 
fc::Local localFilename
 Including the path. More...
 
fc::Remote remoteFilename
 Including the path. More...
 
std::chrono::high_resolution_clock::time_point timeTransferBegan
 The time when the file transfer began. More...
 
std::chrono::high_resolution_clock::time_point timePreviousBlockFinished
 The time when the last block completed. More...
 
std::chrono::high_resolution_clock::duration timeRemaining
 The amount of time left at the current transfer rate. More...
 
std::chrono::high_resolution_clock::time_point timeTransferFinished
 The time when the transfer completed. More...
 
uint64_t payloadBytesTransferred
 The number of payload bytes. More...
 
uint64_t payloadBytesExpected
 The total size of the file being transferred. More...
 
uint64_t payloadBytesSkipped
 The number of bytes that were skipped due to a successful auto-resume of a partial transfer. More...
 
uint64_t bitsPerSecondAverageTransferRate
 Transfer rates measured in bits per second. More...
 
uint64_t bitsPerSecondImmediateTransferRate
 Transfer rates measured in bits per second. More...
 
uint64_t blocksCompleted
 The number of completed transfer blocks. More...
 
uint64_t blocksRemaining
 The number of transfer blocks remaining. More...
 
uint64_t packetsReceived
 The total number of packets received from the server. More...
 
uint64_t packetsSent
 The total number of packets sent to the server (client-side overhead). More...
 
uint64_t duplicatePacketDropped
 The total number of payload packets dropped because we received a duplicate from the server. More...
 
uint64_t requestRetransmit
 The total number of client-side requests made to the server to transmit or retransmit a specific packet. More...
 
uint64_t ackPacketsReceived
 The total number of ack packets. More...
 
uint64_t dataPacketsReceived
 The total number of data packets received. More...
 
uint64_t echoPacketsReceived
 The total number of echo packets received. More...
 
uint64_t metricsPacketsReceived
 The total number of metric packets received. More...
 
uint64_t metricsPacketsSent
 The total number of metric packets sent. More...
 
uint64_t packetLossEvent
 The total number of data packet loss events. More...
 
uint64_t unitSize
 The unit (packet) size. More...
 
uint64_t blockSize
 The block size. More...
 
bool encrypted
 Whether the transfer was encrypted using TCP+SSL or UDP+AES. More...
 
bool upload
 Whether the transfer was an upload or a download. More...
 
uint64_t onTheFlyMd5Received
 On-the-fly MD5 is not supported by FC++, but the packets are counted. More...
 
uint64_t fileReaderStarved
 Number of times when the file reader couldn't proceed with reading the file from disk due to insufficient number of memory buffers. More...
 
uint64_t networkWriterStarved
 Number of times when the network buffer writer couldn't proceed with writing to the socket due to a lack of buffers in the ready-to-write state. More...
 
uint64_t encryptionThreadStarved
 Number of times when one of the encryption threads had no buffers remaining to encrypt. More...
 
uint64_t multipleBlocksInAckNackState
 Number of times when there was multiple blocks simultaneously waiting for ACK/NACK acknowledgment. More...
 
std::string localMd5
 May not be set if MD5 is disabled. More...
 
std::string remoteMd5
 May not be set if MD5 is disabled. More...
 
fc::Local temporaryLocalFilename
 Temporary filename used during transfer. More...
 
fc::Remote temporaryRemoteFilename
 Temporary remote filename prior to being renamed. More...
 

Detailed Description

File transfer statistics.

Note
Not all of the statistics are available for all transfer types.
Warning
There are no thread locks to the transfer stats. Some of these values will periodically update during active file transfers. If this is a concern, please see fc::Control::setStatsCallback() instead.

Also see fc::GlobalStateAndStats which contains a std::map of TransferStats.

While this class initially contained a few simple statistics (thus the name) it has evolved to function as a transfer record, containing everything needed for the FC object to manage multiple sequential file transfers through the use of the std::map known as TransferStatsMap.

Member Enumeration Documentation

◆ EState

Used in several locations to indicate the state of the file transfer.

See also
fc::TransferStats::md5
fc::TransferStats::transfer
fc::TransferStats::type
fc::formatTransferStatsEState()
Enumerator
kInvalid 
kUnknown 
kMd5InProgress 

TransferStats::md5 MD5 verification has started; see fc::Options::setMd5Verification()

kMd5Success 

TransferStats::md5 MD5 verification was successful

kMd5Failed 

TransferStats::md5 MD5 verification failed

kMd5Skipped 

TransferStats::md5 file transfer was skipped since MD5 checksum indicates no changes; see fc::Options::setTransferResume()

kPending 

TransferStats::transfer file is scheduled for transfer, but transfer has not yet started; see fc::Control::prepareSingleFile() or fc::Control::prepareRecursiveDir()

kTransferStarted 

TransferStats::transfer file transfer is in progress

kTransferFinished 

TransferStats::transfer indicates the transfer was successful

kTransferFailed 

TransferStats::transfer transfer did not complete

kFull 

TransferStats::type full transfer (entire file was sent or received)

kPartial 

TransferStats::type only part of the file needed to be transferred (transfer was resumed); see fc::Options::setTransferResume()

kSkippedMD5 

TransferStats::type the entire file was skipped (md5 matched); see fc::Options::setTransferResume()

kSkippedFileExists 

TransferStats::type the entire file was skipped (overwrite mode is disabled); see fc::Options::setOverwrite()

Constructor & Destructor Documentation

◆ TransferStats()

fc::TransferStats::TransferStats ( void  )

Constructor.

References clear().

Here is the call graph for this function:

Member Function Documentation

◆ clear()

◆ operator+=()

◆ getMap()

◆ getStr()

std::string fc::TransferStats::getStr ( const std::string &  header = "",
const bool  all = false 
) const

Similar to getMap(), but append all items to create a single multi-line text string to display for debug purposes.

Parameters
[in]headerText string to include before every line.
[in]allDetermines whether statistics with zero values are included.
See also
fc::TransferStats::getMap()
--showstats

For example:

fc::Control ftp(options);
ftp.upload( my_local_file );
std::cout << stats.getStr("-> ") << std::endl;

...might result in output that looks like this:

-> Average transfer rate: 87.79 Mbps
-> Blocks completed: 80
-> Bytes expected: 150.00 MiB
-> Bytes transferred: 150.71 MiB
-> DATA packets received: 103863
-> Duplicate packets: 35
-> ...etc...

References getMap().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ add_to_map()

fc::StrMap & fc::TransferStats::add_to_map ( fc::StrMap m,
const std::string &  header = "" 
) const

Get the map entries – similar to getmap() – but instead of returning a new map, add the entries to a pre-existing map.

References getMap().

Here is the call graph for this function:

◆ target_local_filename()

fc::Local fc::TransferStats::target_local_filename ( void  ) const
inline

Returns the local filename which should be used.

Normally, this is the same as the "normal" local filename. But when temporary transfer filename support is enabled, this will be different during downloads. Once the transfer has finished, the file is automatically renamed by FC++ from the temporary name to the expected name.

See also
fc::Options::setTmpFilenames()
Since
v0.7.1-1065, September 2016.

References fc::Name::empty(), localFilename, and temporaryLocalFilename.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ target_remote_filename()

fc::Remote fc::TransferStats::target_remote_filename ( void  ) const
inline

Returns the remote filename which should be used.

Normally, this is the same as the "normal" remote filename. But when temporary transfer filename support is enabled, this will be different during uploads. Once the transfer has finished, the file is automatically renamed by FC++ from the temporary name to the expected name.

See also
fc::Options::setTmpFilenames()
Since
v0.7.1-1065, September 2016.

References fc::Name::empty(), remoteFilename, and temporaryRemoteFilename.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ tmp_filename_is_disabled()

bool fc::TransferStats::tmp_filename_is_disabled ( void  ) const
inline

Determine if this file stats object has the necessary filename information to use a temporary filename during transfer.

See also
fc::Options::setTmpFilenames()
Since
v0.7.1-1065, September 2016.

References fc::Name::empty().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ tmp_filename_is_enabled()

bool fc::TransferStats::tmp_filename_is_enabled ( void  ) const
inline

Determine if this file stats object has the necessary filename information to use a temporary filename during transfer.

See also
fc::Options::setTmpFilenames()
Since
v0.7.1-1065, September 2016.

References fc::bps(), fc::formatBytesIEC(), fc::formatBytesOldStyle(), fc::formatBytesSI(), fc::formatTimeDuration(), fc::formatTimeDuration2(), fc::formatTimeRecent(), fc::formatTimestamp(), fc::formatTimestamp2(), fc::formatTransferRate(), fc::formatTransferStatsEState(), tmp_filename_is_disabled(), and fc::to_time_t().

Here is the call graph for this function:
Here is the caller graph for this function:

Member Data Documentation

◆ md5

◆ transfer

EState fc::TransferStats::transfer

State of the file transfer.

For example, see fc::TransferStats::kTransferStarted.

See also
fc::formatTransferStatsEState()

◆ type

EState fc::TransferStats::type

The type of transfer.

For example, see fc::TransferStats::kSkippedFileExists.

See also
fc::formatTransferStatsEState()

◆ localMd5

std::string fc::TransferStats::localMd5

May not be set if MD5 is disabled.

Note
If partial transfers are enabled in the transfer options, then the local and remote MD5 checksum fields may contain just the partial MD5 and not the full MD5 of the entire file.
Since
December 2011.
See also
fc::TransferStats::remoteMd5
fc::TransferStats::md5
fc::Options::setMd5Verification()

◆ remoteMd5

std::string fc::TransferStats::remoteMd5

May not be set if MD5 is disabled.

Since
December 2011.
See also
fc::TransferStats::localMd5
fc::TransferStats::md5
fc::Options::setMd5Verification()

◆ localFilename

fc::Local fc::TransferStats::localFilename

Including the path.

◆ remoteFilename

fc::Remote fc::TransferStats::remoteFilename

Including the path.

◆ temporaryLocalFilename

fc::Local fc::TransferStats::temporaryLocalFilename

Temporary filename used during transfer.

See also
fc::TransferStats::target_local_filename()
fc::TransferStats::target_remote_filename()
fc::Options::setTmpFilenames()
Since
v0.7.1-1065, September 2016.Temporary local filename prior to being renamed.

◆ temporaryRemoteFilename

fc::Remote fc::TransferStats::temporaryRemoteFilename

Temporary remote filename prior to being renamed.

◆ timeTransferBegan

std::chrono::high_resolution_clock::time_point fc::TransferStats::timeTransferBegan

The time when the file transfer began.

Available when using:

  • UDP download
  • UDP upload
  • FTP download
  • FTP upload

◆ timePreviousBlockFinished

std::chrono::high_resolution_clock::time_point fc::TransferStats::timePreviousBlockFinished

The time when the last block completed.

Available when using:

  • UDP download
  • UDP upload

◆ timeRemaining

std::chrono::high_resolution_clock::duration fc::TransferStats::timeRemaining

The amount of time left at the current transfer rate.

Available when using:

  • UDP download
  • UDP upload
  • FTP download
  • FTP upload
Note
This statistic doesn't reflect dropped UDP packets when using UDP upload or UDP download. Thus, the actual file transfer may take longer depending on network conditions. For a coarser counter that can be used to determine what percentage of a UDP transfer remains, see blocksCompleted and blocksRemaining.
Since
v743, December 2011.

◆ timeTransferFinished

std::chrono::high_resolution_clock::time_point fc::TransferStats::timeTransferFinished

The time when the transfer completed.

Available when using:

  • UDP download
  • UDP upload
  • FTP download
  • FTP upload

◆ payloadBytesTransferred

uint64_t fc::TransferStats::payloadBytesTransferred

The number of payload bytes.

This is initially set to zero (for new files) and is incremented during an active file transfer.

  • On downloads: how many payload bytes have been received from the server.
  • On uploads: how many payload bytes have been sent to the server.
Note
This value includes all bytes in payloadBytesSkipped. For example:
  • If the total file size is 4 MiB,
  • but we previously transferred 1 MiB and can resume the transfer,
  • payloadBytesSkipped will indicate 1 MiB,
  • payloadBytesTransferred will start at 1 MiB, and will be incremented to 4 MiB during the file transfer.
Available when using:
  • UDP download
  • UDP upload
  • FTP download
  • FTP upload

◆ payloadBytesExpected

uint64_t fc::TransferStats::payloadBytesExpected

The total size of the file being transferred.

This is set by FC++ prior to the transfer starting, and must never be changed.

Note
This does not take into account any bytes in payloadBytesSkipped and always indicates the full size of the file.

Available when using:

  • UDP download
  • UDP upload
  • FTP download
  • FTP upload

◆ payloadBytesSkipped

uint64_t fc::TransferStats::payloadBytesSkipped

The number of bytes that were skipped due to a successful auto-resume of a partial transfer.

Available when using:

  • UDP download
  • UDP upload
  • FTP download
  • FTP upload
See also
payloadBytesExpected
payloadBytesTransferred
fc::Options::setTransferResume()
Since
v0.7.1-974, September 2015.

◆ bitsPerSecondAverageTransferRate

uint64_t fc::TransferStats::bitsPerSecondAverageTransferRate

Transfer rates measured in bits per second.

This is the data rate at L7, and it does not reflect additional overhead from IP, TCP, UDP, or FileCatalyst headers.

Available when using:

  • UDP download
  • UDP upload
  • FTP download
  • FTP upload
See also
fc::Options::setBandwidth()
Since
v743, December 2011.

◆ bitsPerSecondImmediateTransferRate

uint64_t fc::TransferStats::bitsPerSecondImmediateTransferRate

Transfer rates measured in bits per second.

This is the data rate at L7, and it does not reflect additional overhead from IP, TCP, UDP, or FileCatalyst headers.

Available when using:

  • UDP download
  • UDP upload
  • FTP download
  • FTP upload
See also
fc::Options::setBandwidth()
Since
v743, December 2011.

◆ blocksCompleted

uint64_t fc::TransferStats::blocksCompleted

The number of completed transfer blocks.

Available when using:

  • UDP download
  • UDP upload
See also
fc::Options::setLimits()

◆ blocksRemaining

uint64_t fc::TransferStats::blocksRemaining

The number of transfer blocks remaining.

Available when using:

  • UDP download
  • UDP upload
See also
fc::Options::setLimits()

◆ packetsReceived

uint64_t fc::TransferStats::packetsReceived

The total number of packets received from the server.

This includes both duplicates and overhead non-data packets. Available when using:

  • UDP download
  • UDP upload

◆ packetsSent

uint64_t fc::TransferStats::packetsSent

The total number of packets sent to the server (client-side overhead).

Available when using:

  • UDP download
  • UDP upload

◆ duplicatePacketDropped

uint64_t fc::TransferStats::duplicatePacketDropped

The total number of payload packets dropped because we received a duplicate from the server.

Available when using:

  • UDP download
  • UDP upload

◆ requestRetransmit

uint64_t fc::TransferStats::requestRetransmit

The total number of client-side requests made to the server to transmit or retransmit a specific packet.

Available when using:

  • UDP download
  • UDP upload

◆ ackPacketsReceived

uint64_t fc::TransferStats::ackPacketsReceived

The total number of ack packets.

Available when using:

  • UDP download
  • UDP upload

◆ dataPacketsReceived

uint64_t fc::TransferStats::dataPacketsReceived

The total number of data packets received.

Available when using:

  • UDP download
  • UDP upload

◆ echoPacketsReceived

uint64_t fc::TransferStats::echoPacketsReceived

The total number of echo packets received.

Available when using:

  • UDP download
  • UDP upload

◆ metricsPacketsReceived

uint64_t fc::TransferStats::metricsPacketsReceived

The total number of metric packets received.

Available when using:

  • UDP download
  • UDP upload
Since
v842, March 2012.

◆ metricsPacketsSent

uint64_t fc::TransferStats::metricsPacketsSent

The total number of metric packets sent.

Available when using:

  • UDP download
  • UDP upload
Since
v842, October 2014.

◆ packetLossEvent

uint64_t fc::TransferStats::packetLossEvent

The total number of data packet loss events.

Available when using:

  • UDP upload
Since
v794, October 2014.

◆ unitSize

uint64_t fc::TransferStats::unitSize

The unit (packet) size.

Available when using:

  • UDP download
  • UDP upload
See also
fc::Options::setLimits()
Since
v844, November 2014.

◆ blockSize

uint64_t fc::TransferStats::blockSize

The block size.

Available when using:

  • UDP download
  • UDP upload
See also
fc::Options::setLimits()
Since
v844, November 2014.

◆ encrypted

bool fc::TransferStats::encrypted

Whether the transfer was encrypted using TCP+SSL or UDP+AES.

Available when using:

  • UDP download
  • UDP upload
  • FTP download
  • FTP upload
See also
fc::Options::setEncryption()
Since
v846, November 2014.

◆ upload

bool fc::TransferStats::upload

Whether the transfer was an upload or a download.

This is set to TRUE if uploaded, and FALSE if downloaded. Available when using:

  • UDP download
  • UDP upload
  • FTP download
  • FTP upload
Since
v1060, May 2016.

◆ onTheFlyMd5Received

uint64_t fc::TransferStats::onTheFlyMd5Received

On-the-fly MD5 is not supported by FC++, but the packets are counted.

Since
v1106, June 2017.
See also
fc::Options::setMd5Verification()

◆ fileReaderStarved

uint64_t fc::TransferStats::fileReaderStarved

Number of times when the file reader couldn't proceed with reading the file from disk due to insufficient number of memory buffers.

Available when using:

  • UDP upload
Since
v1118, November 2017.

◆ networkWriterStarved

uint64_t fc::TransferStats::networkWriterStarved

Number of times when the network buffer writer couldn't proceed with writing to the socket due to a lack of buffers in the ready-to-write state.

Available when using:

  • UDP upload
Since
v1118, November 2017.

◆ encryptionThreadStarved

uint64_t fc::TransferStats::encryptionThreadStarved

Number of times when one of the encryption threads had no buffers remaining to encrypt.

This is normal, since the encryption threads will be in an idle state once the entire file has been fully encrypted. Available when using:

  • UDP upload
Since
v1118, November 2017.

◆ multipleBlocksInAckNackState

uint64_t fc::TransferStats::multipleBlocksInAckNackState

Number of times when there was multiple blocks simultaneously waiting for ACK/NACK acknowledgment.

Available when using:

  • UDP upload
Since
v1118, November 2017.

The documentation for this class was generated from the following files: