File transfer statistics. More...

#include <FCTransferStats.hpp>

Collaboration diagram for fc::TransferStats:

[legend]

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 ()
	Constructor. More...

TransferStats &	clear (const bool all=true)
	Clear most or all of the transfer statistics. More...

TransferStats &	operator+= (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::StrMap &	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. More...

fc::Local	target_local_filename () const
	Returns the local filename which should be used. More...

fc::Remote	target_remote_filename () const
	Returns the remote filename which should be used. More...


bool	tmp_filename_is_disabled () 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 () 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

enum fc::TransferStats::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 ( )

Constructor.

References clear().

Here is the call graph for this function:

Member Function Documentation

◆ clear()

fc::TransferStats & fc::TransferStats::clear ( const bool all = true )

Clear most or all of the transfer statistics.

Parameters

[in] all When set to false the values localFilename, remoteFilename, temporaryLocalFilename, temporaryRemoteFilename, and payloadBytesExpected are preserved (not cleared).

References kUnknown.

Here is the caller graph for this function:

◆ operator+=()

fc::TransferStats & fc::TransferStats::operator+= ( const TransferStats & rhs )

Combine transfer statistics to get statistics over several files.

References ackPacketsReceived, blocksCompleted, blocksRemaining, dataPacketsReceived, duplicatePacketDropped, echoPacketsReceived, encrypted, encryptionThreadStarved, fileReaderStarved, kUnknown, metricsPacketsReceived, metricsPacketsSent, multipleBlocksInAckNackState, networkWriterStarved, onTheFlyMd5Received, packetLossEvent, packetsReceived, packetsSent, payloadBytesExpected, payloadBytesSkipped, payloadBytesTransferred, requestRetransmit, timePreviousBlockFinished, timeRemaining, timeTransferBegan, timeTransferFinished, and upload.

◆ getMap()

fc::StrMap fc::TransferStats::getMap ( const std::string & header = "" ) const

Format all the transfer statistics as easy-to-read text strings, and store into a map of strings.

Parameters

[in] header Text string to include before every line.

See also: fc::TransferStats::getStr()

References fc::formatBytesIEC(), fc::formatTimeDuration(), fc::formatTimeRecent(), fc::formatTransferRate(), and fc::formatTransferStatsEState().

Here is the call graph for this function:

◆ 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]	header	Text string to include before every line.
[in]	all	Determines whether statistics with zero values are included.

See also: fc::TransferStats::getMap(); –showstats

For example:

fc::Control ftp(options);
ftp.upload( my_local_file );
const fc::TransferStats &stats = ftp.getMostRecentFileStats();
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...

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.

◆ target_local_filename()

fc::Local fc::TransferStats::target_local_filename ( ) 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, temporaryLocalFilename, and upload.

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 ( ) 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, temporaryRemoteFilename, and upload.

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 ( ) 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(), temporaryLocalFilename, temporaryRemoteFilename, and upload.

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 ( ) 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 tmp_filename_is_disabled().

Here is the call graph for this function:

Member Data Documentation

◆ md5

EState fc::TransferStats::md5

State of the MD5 verification.

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

See also: fc::TransferStats::localMd5; fc::TransferStats::remoteMd5; fc::formatTransferStatsEState(); fc::Options::setMd5Verification()

◆ 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 re-transmissions.

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:

src/publicInclude/FCTransferStats.hpp
src/libfc/FCTransferStats.cpp

Public Types

Public Member Functions

Public Attributes

Detailed Description

Member Enumeration Documentation

◆ EState

Constructor & Destructor Documentation

◆ TransferStats()

Member Function Documentation

◆ clear()

◆ operator+=()

◆ getMap()

◆ getStr()

◆ add_to_map()

◆ target_local_filename()

◆ target_remote_filename()

◆ tmp_filename_is_disabled()

◆ tmp_filename_is_enabled()

Member Data Documentation

◆ md5

◆ transfer

◆ type

◆ localMd5

◆ remoteMd5

◆ localFilename

◆ remoteFilename

◆ temporaryLocalFilename

◆ temporaryRemoteFilename

◆ timeTransferBegan

◆ timePreviousBlockFinished

◆ timeRemaining

◆ timeTransferFinished

◆ payloadBytesTransferred

◆ payloadBytesExpected

◆ payloadBytesSkipped

◆ bitsPerSecondAverageTransferRate

◆ bitsPerSecondImmediateTransferRate

◆ blocksCompleted

◆ blocksRemaining

◆ packetsReceived

◆ packetsSent

◆ duplicatePacketDropped

◆ requestRetransmit

◆ ackPacketsReceived

◆ dataPacketsReceived

◆ echoPacketsReceived

◆ metricsPacketsReceived

◆ metricsPacketsSent

◆ packetLossEvent

◆ unitSize

◆ blockSize

◆ encrypted

◆ upload

◆ onTheFlyMd5Received

◆ fileReaderStarved

◆ networkWriterStarved

◆ encryptionThreadStarved

◆ multipleBlocksInAckNackState