win32-pdh 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5243c26326dadf2f4c5f3cbdb3bfab9a531a1992bbc3b3bc438c8169add75603
-  data.tar.gz: 599302bb34ec10951fdc9c2f260378298dff79b745575b8ac28325cbc2892997
+  metadata.gz: d9f57c2db43f6412bceab31740be7f3131752334ff5b9c5f1f41f634519477bd
+  data.tar.gz: 74ea0ab008113496543dc001d947cbe93b3751eef9fb65be219887eb88921b36
 SHA512:
-  metadata.gz: ecd4510ff8a655d541b6af78b2a6a2b7f0d9487b1916b232479434de13fd31dbe3881b766b0f3a1e681a054decfe9aa4f1b18e5760b1c852926acbb14a59f941
-  data.tar.gz: 0307ddac4aebe77742b783066afb96064dd7c462637136ae27159efc968be98da0ca65bc2fcdd2f454665961d269597780cbd961b6c1f7c39fde027da1e5fa97
+  metadata.gz: 3b569a0bf0cfe35093c065cb527dc521fc503ff40dc882e35afdbfa8ec4036da16cf5cd7ef7003609406a640f77ae97ca93367119b2105a1b890212493a7edbd
+  data.tar.gz: 14e6def409243a45b3e3a51dbf544f9e5df224cbb32252bd9c13920702ccd05f6029e690932eb07618f970977579b694c58cb7539a78f111ccf7482ed2a85077

data/lib/win32/pdh/constants.rb

@@ -104,6 +104,7 @@ module Win32
       PERF_DETAIL_WIZARD = 400
       ERROR_SUCCESS = 0x00000000
 
+      # Value-to-name map, for reverse lookup.
       NAMES = {
         0x00000000 => 'PDH_CSTATUS_VALID_DATA'.freeze,
         0x00000001 => 'PDH_CSTATUS_NEW_DATA'.freeze,
@@ -193,6 +194,7 @@ module Win32
         0xC0000BFE => 'PDH_QUERY_PERF_DATA_TIMEOUT'.freeze,
       }.freeze
 
+      # Value-to-message hash, for generating messages.
       MESSAGES = {
         0x00000000 => 'The returned data is valid.'.freeze,
         0x00000001 => 'The return data value is valid and different from the last sample.'.freeze,

data/lib/win32/pdh/counter.rb

@@ -5,7 +5,12 @@ require 'win32/pdh/constants'
 
 module Win32
   module Pdh
+    ##
+    # Class representing an individual counter.
+    #
+    # This won't usually be created directly, but built using Query#add_counter.
     class Counter
+      # https://msdn.microsoft.com/en-us/library/windows/desktop/aa373041(v=vs.85).aspx
       class PDH_COUNTER_PATH_ELEMENTS < FFI::Struct
         layout(
           :szMachineName, :pointer,
@@ -16,6 +21,7 @@ module Win32
           :szCounterName, :pointer,
         )
       end
+      # https://msdn.microsoft.com/en-us/library/windows/desktop/aa373038(v=vs.85).aspx
       class PDH_COUNTER_INFO < FFI::Struct
         layout(
           :dwLength, :uint,
@@ -33,6 +39,7 @@ module Win32
         )
       end
 
+      # https://msdn.microsoft.com/en-us/library/windows/desktop/aa373050(v=vs.85).aspx
       class PDH_FMT_COUNTERVALUE_VALUE < FFI::Union
         layout(
           :longValue, :int32,
@@ -43,6 +50,7 @@ module Win32
         )
       end
 
+      # https://msdn.microsoft.com/en-us/library/windows/desktop/aa373050(v=vs.85).aspx
       class PDH_FMT_COUNTERVALUE < FFI::Struct
         layout(
           :CStatus, :uint32,
@@ -52,6 +60,9 @@ module Win32
 
       attr_accessor :type, :version, :status, :scale, :default_scale, :full_path, :machine_name, :object_name, :instance_name, :instance_index, :counter_name, :explain_text
 
+      ##
+      # Initializes the counter from a query and a path.  This usually won't be
+      # called directly, but generated from Query#add_counter
       def initialize(query:, path:)
         path = (path + "\0").encode('UTF-16LE')
         handle_pointer = FFI::MemoryPointer.new(:pointer)
@@ -66,6 +77,16 @@ module Win32
         load_info
       end
       
+      ##
+      # Remove the counter from its Query.
+      #
+      # This isn't necessary as a part of general cleanup, as closing a Query
+      # will also clean up all counters.  This is necessary if you are doing
+      # long-term management that may need counters added and removed while
+      # running.  So if you're using a Query as a one-off and it is being closed
+      # after use, don't bother with this.  If you are keeping a single query
+      # open long-term, make sure you use this when necessary, otherwise you
+      # will leak memory.
       def remove
         # Only allow removing once
         unless @handle.nil?
@@ -105,12 +126,20 @@ module Win32
         Pdh.check_status @status
       end
 
-      def good?
-        @status == Constants::ERROR_SUCCESS
-      end
+      private :load_info
 
+      ##
       # Get the PDH_FMT_COUNTERVALUE_VALUE given the format, checking status and
-      # raising an exception if necessary
+      # raising an exception if necessary.
+      #
+      # Usually, you won't use this directly; you'd use #get_double, #get_long,
+      # or #get_large to get the formatted value without any hassle.
+      #
+      # Will raise a PdhError if the value is bad (if you've only run
+      # Query#collect_query_data once, but this counter requires a history to
+      # calculate a rate, this will raise an exception.  Be careful, and
+      # probably wrap all calls to this in an exception block that takes into
+      # account the possibility of a counter failing to get a value)
       def get(format)
         value = PDH_FMT_COUNTERVALUE.new
         status = PdhFFI.PdhGetFormattedCounterValue(
@@ -125,19 +154,25 @@ module Win32
       end
 
       ##
-      # Get value as a double
+      # Get value as a double.
+      #
+      # This uses #get, so read the notes in there about exception raising.
       def get_double
         get(Constants::PDH_FMT_DOUBLE)[:doubleValue]
       end
 
       ##
-      # Get value as a 64-bit integer
+      # Get value as a 64-bit integer.
+      #
+      # This uses #get, so read the notes in there about exception raising.
       def get_large
         get(Constants::PDH_FMT_LARGE)[:largeValue]
       end
 
       ##
       # Get value as a 32-bit integer
+      #
+      # This uses #get, so read the notes in there about exception raising.
       def get_long
         get(Constants::PDH_FMT_LONG)[:longValue]
       end

data/lib/win32/pdh/query.rb

@@ -3,6 +3,8 @@ require 'win32/pdh/counter'
 
 module Win32
   module Pdh
+    ##
+    # Class representing a Query, and holding a query handle.
     class Query
       def initialize(source=nil)
         source =
@@ -13,7 +15,7 @@ module Win32
           end
         handle_pointer = FFI::MemoryPointer.new(:pointer)
         status = PdhFFI.PdhOpenQueryW(source, FFI::Pointer::NULL, handle_pointer)
-        raise PdhError, status unless status == Constants::ERROR_SUCCESS
+        Pdh.check_status status
         @handle = handle_pointer.read_pointer
       end
       
@@ -21,18 +23,20 @@ module Win32
         # Only allow closing once
         unless @handle.nil?
           status = PdhFFI.PdhCloseQuery(@handle)
-          raise PdhError, status unless status == Constants::ERROR_SUCCESS
+          Pdh.check_status status
           @handle = nil
         end
       end
 
       ##
-      # Simple query opening function.  Uses the OpenQuery function and gets a
-      # query, passes it into the block, and then closes it afterward.  If no
-      # block is given, it just returns the query, and you are responsible for
-      # closing it.  The GC will not close this for you, so you can easily leak
-      # resources.  It's strongly recommended to use the block style if at all
-      # possible to ensure resource cleanup.
+      # Simple query opening function.
+      #
+      # Uses the OpenQuery function and gets a query, passes it into the block,
+      # and then closes it afterward.  If no block is given, it just returns the
+      # query, and you are responsible for closing it.  The GC will not close
+      # this for you, so you can easily leak resources.  It's strongly
+      # recommended to use the block style if at all possible to ensure resource
+      # cleanup.
       def self.open(source=nil)
         query = new source
         if block_given?
@@ -46,12 +50,18 @@ module Win32
         end
       end
 
+      ##
+      # Simple wrapper around PdhIsRealTimeQuery.
+      #
+      # https://msdn.microsoft.com/en-us/library/windows/desktop/aa372646(v=vs.85).aspx
       def real_time?
         PdhFFI.PdhIsRealTimeQuery(@handle) == :true
       end
 
       ##
       # Adds a counter to this query and return it as a Counter object.
+      #
+      # https://msdn.microsoft.com/en-us/library/windows/desktop/aa372204(v=vs.85).aspx
       def add_counter(path)
         Counter.new(
           query: @handle,
@@ -59,6 +69,12 @@ module Win32
         )
       end
 
+      ##
+      # Calls PdhCollectQueryData.  This is necessary to load counters with data
+      # before retreiving it.
+      #
+      # Some counters may need this called twice before they can retreive the
+      # data.  CPU counters are obvious examples.
       def collect_query_data
         status = PdhFFI.PdhCollectQueryData(@handle)
         Pdh.check_status status

data/lib/win32/pdh.rb

@@ -4,6 +4,9 @@ require 'ffi'
 
 module Win32
   module Pdh
+    ##
+    # Simple error subclass.  Currently, this is what type all exceptions
+    # directly raised by this library are.
     class PdhError < StandardError
       def initialize(status)
         super("PDH error #{Constants::NAMES[status]}: #{Constants::MESSAGES[status]}")
@@ -36,6 +39,8 @@ module Win32
       array.pack('n*').force_encoding('UTF-16BE').encode('UTF-8')
     end
 
+    ##
+    # Container namespace for all Pdh functions.
     module PdhFFI
       extend FFI::Library
       ffi_lib 'Pdh.dll'
@@ -69,12 +74,14 @@ module Win32
 
     ##
     # Uses PdhEnumObjects to enumerate objects at the given target.  Returns the
-    # objects as a list.
+    # objects as an array of strings.
+    #
+    # PdhEnumObjects: https://msdn.microsoft.com/en-us/library/windows/desktop/aa372600(v=vs.85).aspx
     #
     # Params:
-    # +source+:: The same as szDataSource
-    # +machine+:: The same as szMachineName
-    # +detail+:: Alias for dwDetailLevel, as a symbol.  May be :novice, :advanced, :expert, or :wizard.  Defaults to :novice.
+    # source:: The same as szDataSource
+    # machine:: The same as szMachineName
+    # detail:: Alias for dwDetailLevel, as a symbol.  May be :novice, :advanced, :expert, or :wizard.  Defaults to :novice.
     def self.enum_objects(source: nil, machine: nil, detail: :novice)
       source =
         if source.nil?
@@ -125,11 +132,15 @@ module Win32
       string.split("\0")
     end
 
+    ##
+    # Structure of instances and counters, for ::enum_object_items
     ItemEnum = Struct.new('ItemEnum', :instances, :counters)
 
     ##
     # Enumerates an object's counter and instance names.  Returns an ItemEnum
     # with the results.
+    #
+    # Uses PdhEnumObjectItems: https://msdn.microsoft.com/en-us/library/windows/desktop/aa372595(v=vs.85).aspx
     def self.enum_object_items(object:, source: nil, machine: nil, detail: :novice)
       object = (object + "\0").encode('UTF-16LE')
       source =
@@ -194,6 +205,10 @@ module Win32
 
     ##
     # Expands a wildcard path into all matching counter paths.
+    #
+    # Returns a frozen array of frozen strings.
+    #
+    # Uses PdhExpandWildCardPath: https://msdn.microsoft.com/en-us/library/windows/desktop/aa372606(v=vs.85).aspx
     def self.expand_wildcards(path:, source: nil, expand_counters: true, expand_instances: true)
       path = (path + "\0").encode('UTF-16LE')
       source =

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: win32-pdh
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Taylor C. Richberger
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-04-16 00:00:00.000000000 Z
+date: 2018-04-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi