Merge pull request #12 from UniStuttgart-VISUS/sal

SAL annotations

Author: crowbar27

README.md

@@ -37,7 +37,7 @@ Some sensors have a slightly different API. For instance, sensors using *Tinkerf
 ```c++
 using namespace visus::power_overwhelming;
 
-std::vector<tinkerforge_sensor_definiton> descs;
+std::vector<tinkerforge_sensor_definition> descs;
 // Call 'get_definitions' to find out how many definitions there are.
 descs.resize(tinkerforge_sensor::get_definitions(nullptr, 0));
 // Call 'get_definitions' to get the actual descriptors.

podump/tinkerforge.cpp

@@ -14,7 +14,7 @@ void sample_tinkerforge_sensor(void) {
     using namespace visus::power_overwhelming;
 
     try {
-        std::vector<tinkerforge_sensor_definiton> descs;
+        std::vector<tinkerforge_sensor_definition> descs;
         descs.resize(tinkerforge_sensor::get_definitions(nullptr, 0));
         auto cnt = tinkerforge_sensor::get_definitions(descs.data(),
             descs.size());
@@ -47,7 +47,7 @@ void sample_tinkerforge_sensor_async(const unsigned int dt) {
     using namespace visus::power_overwhelming;
 
     try {
-        std::vector<tinkerforge_sensor_definiton> descs;
+        std::vector<tinkerforge_sensor_definition> descs;
         std::vector<tinkerforge_sensor> sensors;
         descs.resize(tinkerforge_sensor::get_definitions(nullptr, 0));
         auto cnt = tinkerforge_sensor::get_definitions(descs.data(),

power_overwhelming/CMakeLists.txt

@@ -56,11 +56,9 @@ target_include_directories(${PROJECT_NAME}
     PRIVATE
         $<BUILD_INTERFACE:${SourceDir}>)
 
-target_link_libraries(${PROJECT_NAME} PRIVATE
-    nlohmann_json
-    adl
-    nvml
-    tinkerforge)
+target_link_libraries(${PROJECT_NAME}
+    PUBLIC salieri
+    PRIVATE adl nlohmann_json nvml tinkerforge)
 
 if (WIN32)
     target_link_libraries(${PROJECT_NAME} PUBLIC Ws2_32)

power_overwhelming/include/power_overwhelming/adl_sensor.h

@@ -37,8 +37,9 @@ namespace power_overwhelming {
         /// of the size of the output array. If this number is larger than
         /// <paramref name="cntSensors" />, not all sensors have been returned.
         /// </returns>
-        static std::size_t for_all(adl_sensor *outSensors,
-            const std::size_t cntSensors);
+        static std::size_t for_all(
+            _Out_writes_opt_(cntSensors) adl_sensor *outSensors,
+            _In_ const std::size_t cntSensors);
 
         /// <summary>
         /// Create a new instance for the specified adapter index.
@@ -50,8 +51,8 @@ namespace power_overwhelming {
         /// <returns></returns>
         /// <exception cref="adl_exception">If the specified device was not
         /// found, or another error occurred in ADL.</exception>
-        static adl_sensor from_index(const int index,
-            const adl_sensor_source source);
+        static adl_sensor from_index(_In_ const int index,
+            _In_ const adl_sensor_source source);
 
         /// <summary>
         /// Create a new instance for the unique device ID.
@@ -66,8 +67,24 @@ namespace power_overwhelming {
         /// </exception>
         /// <exception cref="adl_exception">If the specified device was not
         /// found, or another error occurred in ADL.</exception>
-        static adl_sensor from_udid(const char *udid,
-            const adl_sensor_source source);
+        static adl_sensor from_udid(_In_z_ const char *udid,
+            _In_ const adl_sensor_source source);
+
+        /// <summary>
+        /// Create a new instance for the unique device ID.
+        /// </summary>
+        /// <param name="udid">The unique device ID to create the sensor for.
+        /// </param>
+        /// <param name="source">The sensor source to retrieve. If the source
+        /// is not supported, the method will fail.</param>
+        /// <returns></returns>
+        /// <exception cref="std::invalid_argument">If <paramref name="udid" />
+        /// is <c>nullptr</c> or if it did not match exactly one device.
+        /// </exception>
+        /// <exception cref="adl_exception">If the specified device was not
+        /// found, or another error occurred in ADL.</exception>
+        static adl_sensor from_udid(_In_z_ const wchar_t *udid,
+            _In_ const adl_sensor_source source);
 
         /// <summary>
         /// Initialises a new instance.
@@ -85,7 +102,7 @@ namespace power_overwhelming {
         /// </summary>
         /// <param name="rhs"></param>
         /// <returns></returns>
-        inline adl_sensor(adl_sensor&& rhs) noexcept : _impl(rhs._impl) {
+        inline adl_sensor(_In_ adl_sensor&& rhs) noexcept : _impl(rhs._impl) {
             rhs._impl = nullptr;
         }
 
@@ -98,7 +115,8 @@ namespace power_overwhelming {
         /// <param name="impl">The status block, which must have been allocated
         /// using <c>new</c>. The object takes ownership of the status block.
         /// </param>
-        inline explicit adl_sensor(detail::adl_sensor_impl *&& impl) noexcept
+        inline explicit adl_sensor(
+                _In_ detail::adl_sensor_impl *&& impl) noexcept
                 : _impl(impl) {
             impl = nullptr;
         }
@@ -113,7 +131,8 @@ namespace power_overwhelming {
         /// </summary>
         /// <returns>The implementation-defined, human-readable name of the
         /// sensor.</returns>
-        virtual const wchar_t *name(void) const noexcept override;
+        virtual _Ret_maybenull_z_ const wchar_t *name(
+            void) const noexcept override;
 
         /// <summary>
         /// Sample the sensor.
@@ -127,7 +146,7 @@ namespace power_overwhelming {
         /// <exception cref="adl_exception">If the sensor could not be sampled.
         /// </exception>
         virtual measurement sample(
-            const timestamp_resolution resolution) const override;
+            _In_ const timestamp_resolution resolution) const override;
 
         /// <summary>
         /// Asynchronously sample the sensor every
@@ -144,7 +163,7 @@ namespace power_overwhelming {
         /// <param name="on_measurement">The callback to be invoked if new data
         /// arrived. If this is <c>nullptr</c>, the asynchronous sampling will
         /// be disabled.</param>
-        /// <param name="sampling_period">The desired sampling period in
+        /// <param name="period">The desired sampling period in
         /// microseconds. This parameter defaults to 1 millisecond.</param>
         /// <param name="context">A user-defined context pointer that is passed
         /// on to <see cref="on_measurement" />. This parameter defaults to
@@ -156,9 +175,9 @@ namespace power_overwhelming {
         /// </exception>
         /// <exception cref="tinkerforge_exception">If the sensor could not be
         /// sampled. </exception>
-        void sample(const measurement_callback on_measurement,
-            const microseconds_type sampling_period = default_sampling_period,
-            void *context = nullptr);
+        void sample(_In_opt_ const measurement_callback on_measurement,
+            _In_ const microseconds_type period = default_sampling_period,
+            _In_opt_ void *context = nullptr);
 
         using sensor::sample;
 
@@ -181,7 +200,7 @@ namespace power_overwhelming {
         /// the sensor is already asynchronously collecting data.</exception>
         /// <exception cref="adl_exception">If the source could not be
         /// started.</exception>
-        void start(const microseconds_type sampling_period);
+        void start(_In_ const microseconds_type sampling_period);
 
         /// <summary>
         /// Stops the sensor from asynchronously collecting data.
@@ -207,14 +226,14 @@ namespace power_overwhelming {
         /// </summary>
         /// <param name=""></param>
         /// <returns></returns>
-        const char *udid(void) const noexcept;
+        _Ret_maybenull_z_ const char *udid(void) const noexcept;
 
         /// <summary>
         /// Move assignment.
         /// </summary>
         /// <param name="rhs">The right-hand side operand</param>
         /// <returns><c>*this</c></returns>
-        adl_sensor& operator =(adl_sensor&& rhs) noexcept;
+        adl_sensor& operator =(_In_ adl_sensor&& rhs) noexcept;
 
         /// <summary>
         /// Determines whether the sensor is valid.

power_overwhelming/include/power_overwhelming/collector.h

@@ -37,7 +37,7 @@ namespace power_overwhelming {
         /// <param name="settings">The general settings for the collector,
         /// including the sampling interval.</param>
         /// <returns>A collector for all available sensors.</returns>
-        static collector for_all(const collector_settings& settings);
+        static collector for_all(_In_ const collector_settings& settings);
 
         /// <summary>
         /// Creates a collector for all sensors that could be found and
@@ -50,8 +50,8 @@ namespace power_overwhelming {
         /// <returns>A collector for all available sensors.</returns>
         /// <exception std::invalid_argument">If <paramref name="output_path" />
         /// is <c>nullptr</c>.</exception>
-        inline static collector for_all(const wchar_t *output_path,
-                const sensor::microseconds_type sampling_interval
+        inline static collector for_all(_In_z_ const wchar_t *output_path,
+                _In_ const sensor::microseconds_type sampling_interval
                 = collector_settings::default_sampling_interval) {
             return for_all(collector_settings().output_path(output_path)
                 .sampling_interval(sampling_interval));
@@ -71,7 +71,7 @@ namespace power_overwhelming {
         /// <param name="path">The path to the JSON configuration file.</param>
         /// <returns>A new collector configured with the sensors in the
         /// specified file.</returns>
-        static collector from_json(const wchar_t *path);
+        static collector from_json(_In_z_ const wchar_t *path);
 
         /// <summary>
         /// Initialise a new instance from the given lists of sensors.
@@ -84,7 +84,8 @@ namespace power_overwhelming {
         /// <param name="sensors">The lists of sensors.</param>
         /// <returns></returns>
         template<class... TSensorLists>
-        static collector from_sensor_lists(const collector_settings& settings,
+        static collector from_sensor_lists(
+            _In_ const collector_settings& settings,
             TSensorLists&&... sensors);
 
         /// <summary>
@@ -100,7 +101,7 @@ namespace power_overwhelming {
         /// disposed by moving them once the method returns.</param>
         /// <returns>A new collector using the given sensors.</returns>
         template<class... TSensors>
-        static collector from_sensors(const collector_settings& settings,
+        static collector from_sensors(_In_ const collector_settings& settings,
             TSensors&&... sensors);
 
         /// <summary>
@@ -118,7 +119,7 @@ namespace power_overwhelming {
         /// </remarks>
         /// <param name="path">The path where the configuration file should be
         /// stored.</param>
-        static void make_configuration_template(const wchar_t *path);
+        static void make_configuration_template(_In_z_ const wchar_t *path);
 
         /// <summary>
         /// Initialise a new instance.
@@ -135,7 +136,7 @@ namespace power_overwhelming {
         /// </summary>
         /// <param name="rhs"></param>
         /// <returns></returns>
-        inline collector(collector&& rhs) noexcept : _impl(rhs._impl) {
+        inline collector(_In_ collector&& rhs) noexcept : _impl(rhs._impl) {
             rhs._impl = nullptr;
         }
 
@@ -149,7 +150,7 @@ namespace power_overwhelming {
         /// output.
         /// </summary>
         /// <param name="marker"></param>
-        void marker(const wchar_t *marker);
+        void marker(_In_opt_z_ const wchar_t *marker);
 
         /// <summary>
         /// Answer the number of sensors in the collector.
@@ -177,7 +178,7 @@ namespace power_overwhelming {
         /// </summary>
         /// <param name="rhs">The right-hand side operand</param>
         /// <returns><c>*this</c></returns>
-        collector& operator =(collector&& rhs) noexcept;
+        collector& operator =(_In_ collector&& rhs) noexcept;
 
         /// <summary>
         /// Determines whether the object is valid.
@@ -209,14 +210,15 @@ namespace power_overwhelming {
         /// <param name="settings"></param>
         /// <param name="capacity"></param>
         /// <returns>A new collector without sensors.</returns>
-        static collector prepare(const collector_settings& settings,
-            const std::size_t capacity);
+        static collector prepare(_In_ const collector_settings& settings,
+            _In_ const std::size_t capacity);
 
         /// <summary>
         /// Initialise a new instance.
         /// </summary>
         /// <param name="impl"></param>
-        inline collector(detail::collector_impl *impl) : _impl(impl) { }
+        inline collector(_In_opt_ detail::collector_impl *impl)
+            : _impl(impl) { }
 
         /// <summary>
         /// Adds a new sensor to the collector.
@@ -229,7 +231,7 @@ namespace power_overwhelming {
         /// <param name="sensor">The sensor to be added. The object takes
         /// ownership of the object designated by this pointer. The object
         /// must have been allocated using C++ <c>new</c>.</param>
-        void add(sensor *sensor);
+        void add(_In_ sensor *sensor);
 
         detail::collector_impl *_impl;
 

power_overwhelming/include/power_overwhelming/collector.inl

@@ -10,7 +10,8 @@
 template<class... TSensorLists>
 visus::power_overwhelming::collector
 visus::power_overwhelming::collector::from_sensor_lists(
-        const collector_settings& settings, TSensorLists&&... sensors) {
+        _In_ const collector_settings& settings,
+        TSensorLists&&... sensors) {
     std::array<std::vector<std::unique_ptr<sensor>>,
         sizeof...(sensors)> instances = { move_to_heap(sensors)... };
     typedef typename decltype(instances)::value_type sensor_type;
@@ -39,7 +40,8 @@ visus::power_overwhelming::collector::from_sensor_lists(
 template<class... TSensors>
 visus::power_overwhelming::collector
 visus::power_overwhelming::collector::from_sensors(
-        const collector_settings& settings, TSensors&&... sensors) {
+        _In_ const collector_settings& settings,
+        TSensors&&... sensors) {
     std::array<std::unique_ptr<sensor>, sizeof...(sensors)> instances = {
         std::unique_ptr<sensor>(new typename std::decay<TSensors>::type(
             std::move(sensors)))...

power_overwhelming/include/power_overwhelming/collector_settings.h

@@ -48,7 +48,7 @@ namespace power_overwhelming {
         /// Clone <paramref name="rhs" />.
         /// </summary>
         /// <param name="rhs">The object to be cloned.</param>
-        collector_settings(const collector_settings& rhs);
+        collector_settings(_In_ const collector_settings& rhs);
 
         /// <summary>
         /// Finalises the instance.
@@ -60,7 +60,7 @@ namespace power_overwhelming {
         /// output to.
         /// </summary>
         /// <returns>The path to the output file.</returns>
-        inline const wchar_t *output_path(void) const noexcept {
+        inline _Ret_z_ const wchar_t *output_path(void) const noexcept {
             return this->_output_path;
         }
 
@@ -72,7 +72,7 @@ namespace power_overwhelming {
         /// <returns><c>*this</c>.</returns>
         /// <exception cref="std::invalid_argument">If
         /// <paramref name="output_path" /> is <c>nullptr</c>.</exception>
-        collector_settings& output_path(const wchar_t *path);
+        collector_settings& output_path(_In_z_ const wchar_t *path);
 
         /// <summary>
         /// Gets the time interval in which the collector should sample the
@@ -89,14 +89,14 @@ namespace power_overwhelming {
         /// <param name="interval">The sampling interval.</param>
         /// <returns><c>*this</c>.</returns>
         collector_settings& sampling_interval(
-            const sampling_interval_type interval);
+            _In_ const sampling_interval_type interval);
 
         /// <summary>
         /// Assignment.
         /// </summary>
         /// <param name="rhs">The right hand side operand.</param>
         /// <returns><c>*this</c>.</returns>
-        collector_settings& operator =(const collector_settings& rhs);
+        collector_settings& operator =(_In_ const collector_settings& rhs);
 
     private:
 

power_overwhelming/include/power_overwhelming/computer_name.h

@@ -32,8 +32,9 @@ namespace power_overwhelming {
     /// store the computer name, including the terminating null.</returns>
     /// <exception cref="std::system_error">In case the operation failed.
     /// </exception>
-    std::size_t POWER_OVERWHELMING_API computer_name(char *dst,
-        const std::size_t cnt);
+    std::size_t POWER_OVERWHELMING_API computer_name(
+        _Out_writes_opt_z_(cnt) char *dst,
+        _In_ const std::size_t cnt);
 
     /// <summary>
     /// Answer the name of the computer the calling code is running on.
@@ -52,8 +53,9 @@ namespace power_overwhelming {
     /// store the computer name, including the terminating null.</returns>
     /// <exception cref="std::system_error">In case the operation failed.
     /// </exception>
-    std::size_t POWER_OVERWHELMING_API computer_name(wchar_t *dst,
-        const std::size_t cnt);
+    std::size_t POWER_OVERWHELMING_API computer_name(
+        _Out_writes_opt_z_(cnt) wchar_t *dst,
+        _In_ const std::size_t cnt);
 
     /// <summary>
     /// Answer the name of the computer the calling code is running on.