kvikio::Monitor Class Reference

Watches operations, from the moment they start until they finish. More...

#include <observation.hpp>

Public Member Functions
	Monitor (Monitor const &)=delete
Monitor &	operator= (Monitor const &)=delete
virtual void	on_start (Observation const &observation) noexcept=0
	An operation has started. More...
virtual void	on_finish (Observation const &observation) noexcept=0
	An operation has completed. More...

Detailed Description

Watches operations, from the moment they start until they finish.

Derive from this and register it to be told what KvikIO is doing. Two notifications per operation: on_start() when it begins, carrying the record as it stands at submission, and on_finish() when it ends, carrying the finished record.

A monitor is told about user-facing calls: one FileHandle::pread() is one operation however many reads KvikIO issued underneath.

Note

Not everything is reported:

• The cuFile asynchronous API (FileHandle::read_async(), FileHandle::write_async()) on a system with working GDS reports nothing. In compatibility mode those calls fall back to read()/write() and are reported, so the same program is seen differently depending on whether GDS is available.
• The batch API (BatchHandle) reports nothing.
• RemoteHandle::pread() into device memory finishes when the last pinned-to-device copy is issued rather than completed, so its span is slightly short. It is never too long.

// Reports how many KvikIO operations are in flight at any moment.
class QueueDepth : public kvikio::Monitor {
 public:
  [[nodiscard]] int depth() const noexcept { return _in_flight.load(); }
 
 private:
  void on_start(kvikio::Observation const&) noexcept override { ++_in_flight; }
  void on_finish(kvikio::Observation const&) noexcept override { --_in_flight; }
 
  std::atomic<int> _in_flight{0};
};
 
QueueDepth gauge;
auto const id = kvikio::register_monitor(&gauge);
...
kvikio::unregister_monitor(id);  // Waits, so `gauge` may now be destroyed.

Every operation that reports a start reports exactly one finish, on whichever thread does the work.

Warning

A monitor runs inline with the I/O, on the thread performing it, on both the submission and the completion path. Keep it light, make it thread-safe, and do not call back into KvikIO, which throws std::runtime_error. Neither callback may throw.

Definition at line 256 of file observation.hpp.

Member Function Documentation

on_finish()

virtual void kvikio::Monitor::on_finish ( Observation const &  observation )

pure virtualnoexcept

An operation has completed.

A monitor registered after observation.start never saw the matching on_start(), and should ignore such an operation.

Warning

Runs inline with the I/O, on the thread performing it. Keep it light, make it thread-safe, and do not call back into KvikIO, which throws std::runtime_error.

Parameters

observation

The completed operation. The reference is valid only for the duration of this call. Copy what is needed later.

on_start()

virtual void kvikio::Monitor::on_start ( Observation const &  observation )

pure virtualnoexcept

An operation has started.

The observation is not finished: end and bytes_transferred are zero, and ok is true only because nothing has failed yet. All three are set by the time on_finish() is called.

Warning

Runs inline with the I/O, on the thread performing it. Keep it light, make it thread-safe, and do not call back into KvikIO, which throws std::runtime_error.

Parameters

observation

The operation, as far as it is known. The reference is valid only for the duration of this call. Copy what is needed later.

---

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

• observation.hpp