C++ （opaque） handle

handle

Handle是一個指標或索引，被用來存取某項資源。範例可以參考What is a handle in C++? - jmucchiello。

opaque handle

Opaque handle則是一個在定義時看不到它的內容的一種handle。詳見Opaque Pointer。

在TensorRT/samples/common/logging.h裡，TestAtom是一個存取logging information（所謂的資源）的opaque handle：

class Logger : public nvinfer1::ILogger
{
public:
	//!
	//! \brief Opaque handle that holds logging information for a particular test
	//!
	//! This object is an opaque handle to information used by the Logger to print test results.
	//! The sample must call Logger::defineTest() in order to obtain a TestAtom that can be used
	//! with Logger::reportTest{Start,End}().
	//!
	class TestAtom
	{
	public:
	    TestAtom(TestAtom&&) = default;
	
	private:
	    friend class Logger;
	
	    TestAtom(bool started, const std::string& name, const std::string& cmdline)
	        : mStarted(started)
	        , mName(name)
	        , mCmdline(cmdline)
	    {
	    }
	
	    bool mStarted;
	    std::string mName;
	    std::string mCmdline;
	};

    //...
    
	//!
	//! \brief Define a test for logging
	//!
	//! \param[in] name The name of the test.  This should be a string starting with
	//!                  "TensorRT" and containing dot-separated strings containing
	//!                  the characters [A-Za-z0-9_].
	//!                  For example, "TensorRT.sample_googlenet"
	//! \param[in] cmdline The command line used to reproduce the test
	//
	//! \return a TestAtom that can be used in Logger::reportTest{Start,End}().
	//!
	static TestAtom defineTest(const std::string& name, const std::string& cmdline)
	{
	    return TestAtom(false, name, cmdline);
	}
	
	//!
	//! \brief A convenience overloaded version of defineTest() that accepts an array of command-line arguments
	//!        as input
	//!
	//! \param[in] name The name of the test
	//! \param[in] argc The number of command-line arguments
	//! \param[in] argv The array of command-line arguments (given as C strings)
	//!
	//! \return a TestAtom that can be used in Logger::reportTest{Start,End}().
	static TestAtom defineTest(const std::string& name, int argc, char const* const* argv)
	{
	    auto cmdline = genCmdlineString(argc, argv);
	    return defineTest(name, cmdline);
	}
	
	//!
	//! \brief Report that a test has started.
	//!
	//! \pre reportTestStart() has not been called yet for the given testAtom
	//!
	//! \param[in] testAtom The handle to the test that has started
	//!
	static void reportTestStart(TestAtom& testAtom)
	{
	    reportTestResult(testAtom, TestResult::kRUNNING);
	    assert(!testAtom.mStarted);
	    testAtom.mStarted = true;
	}
	    
	
	//!
	//! \brief Report that a test has ended.
	//!
	//! \pre reportTestStart() has been called for the given testAtom
	//!
	//! \param[in] testAtom The handle to the test that has ended
	//! \param[in] result The result of the test. Should be one of TestResult::kPASSED,
	//!                   TestResult::kFAILED, TestResult::kWAIVED
	//!
	static void reportTestEnd(const TestAtom& testAtom, TestResult result)
	{
	    assert(result != TestResult::kRUNNING);
	    assert(testAtom.mStarted);
	    reportTestResult(testAtom, result);
	}
	
	static int reportPass(const TestAtom& testAtom)
	{
	    reportTestEnd(testAtom, TestResult::kPASSED);
	    return EXIT_SUCCESS;
	}
	
	static int reportFail(const TestAtom& testAtom)
	{
	    reportTestEnd(testAtom, TestResult::kFAILED);
	    return EXIT_FAILURE;
	}
	
	static int reportWaive(const TestAtom& testAtom)
	{
	    reportTestEnd(testAtom, TestResult::kWAIVED);
	    return EXIT_SUCCESS;
	}
	
	static int reportTest(const TestAtom& testAtom, bool pass)
	{
	    return pass ? reportPass(testAtom) : reportFail(testAtom);
	}
	
	//!
	//! \brief method that implements logging test results
	//!
	static void reportTestResult(const TestAtom& testAtom, TestResult result)
	{
	    severityOstream(Severity::kINFO) << "&&&& " << testResultString(result) << " " << testAtom.mName << " # "
	                                     << testAtom.mCmdline << std::endl;
	}
	
	//...
};

當我們手上有一個TestAtom，我們無從知道它所包含的log資訊（因為它的成員變數都是private的）。

我們必須調用與其相關的函數（如 Logger::reportTestStart ）才能"間接地"獲取這些資訊（此處透過friend class的機制使得Logger::reportTestStart擁有對TestAtom的私有成員變數的存取權，關於friend class，可參考C++ friend class）。也因此註釋裡才說TestAtom是一個opaque handle。

參考連結

Wiki - Handle (computing)

What is a handle in C++?

Opaque Pointer

C++ friend class