linux_stat 0.6.3 → 0.6.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05ad75bfd711c7ac7960645e2609416e868f2b425cbac94b503198db8b011aa4
-  data.tar.gz: f6291a5aaa6903839d7915c8e8494d88cf165dd6e82143ff0fc71dcea19628d8
+  metadata.gz: 15bbdf4582dc8a526cde2230d81e2fea8ea67f5684daeae87161bd486e8f73a0
+  data.tar.gz: 236125a3f4ac8c85563cf075be40b8ceb0e7e0b4cd6374abce1c6c6f62da8d56
 SHA512:
-  metadata.gz: f4406f12e2035652f26f9eb518bb4386e644622938d506880cc3f2899937e060b594d6067a8b4a4b66c85db24f068b13a70e59cbac4f9770cc937569e506da26
-  data.tar.gz: b0bbb6cd4570228bafaa2fe89d2bc6a75e67803334e907bcf6e3c3a3fb70f1333ac98da133484b37d8fe279d991ffd18cad617fa931f77c9c7150798cc2d580a
+  metadata.gz: 9c2f0f12aa42dbb2c63426a5c7aa384bb68a02dcf283b78953ebc641b6d1803400f571d94e6eb4a812b282672d95a071857fd2e4ab4004d17c163eb2ce12fea7
+  data.tar.gz: 448f627019dce4ada6c6c76c75dc3a2d531230a1cf77de7a88d0fd372c43e79ed69b479dc7625385ac9f2e44e1bb8da2ef8405d9737ddccd5b985691959cf294

data/README.md

@@ -514,7 +514,71 @@ LinuxStat::User.usernames_by_uid
 
 ---
 
-## Note 1: Filesystem
+## Note 1: CPU usage, and Net usage
+To calculate the current usage, we need to get two usages at a given interval, and subtract the 2nd from the 1st.
+For example, if the current download (`LinuxStat::Net.total_bytes_received`) is 1000 bytes, and if 0.1 seconds ago, it was 100 bytes, that means 900 bytes was received in 0.1 seconds.
+That means the current speed is 9000 bytes/s or 9 kB/s.
+
+Without the polling, it's not really possible to calculate the current usage. Although the total usage can be calculated.
+A system monitor does that, too...
+
+Thus these methods requires a polling interval:
+
+1. LinuxStat::CPU.stat, usage, total_usage, usage.
+2. LinuxStat::ProcessInfo.cpu_usage, cpu_stat.
+3. LinuxStat::Net.usage, current_usage.
+
+They sleep for a given interval and then differentiate between the data.
+
+For more info look at the ri documentation for the above methods.
+
+These methods can slow down your application a bit unless you implement them in a thread.
+
+Other methods doesn't have the sleep implemented, and they just works under a millisecond.
+
+For example:
+
+```
+LinuxStat::CPU.stat(0.1)
+=> {0=>7.69, 1=>0.0, 2=>0.0, 3=>18.18, 4=>10.0}
+```
+This will sleep for 0.1 seconds. To be reliable, use a time like 0.05 seconds or so.
+
+If you want to build a system monitor and don't want to wait, you have to do something like this:
+
+```
+#!/usr/bin/ruby
+require 'linux_stat'
+
+usages = []
+thread = Thread.new { }
+counter = 0
+
+while true
+	thread = Thread.new { usages = LinuxStat::CPU.usages(0.5).values } unless thread.alive?
+
+	# clears the screen and prints the info
+	puts "\e[2J\e[H\e[3J"\
+	"#{counter += 1}\n"\
+	"\e[1;33mTotal CPU Usage:\e[0m #{usages[0]}%\n"\
+	"#{usages[1..-1].to_a.map.with_index { |x, i| "\e[1;33mCore #{i}\e[0m => #{x}%\n" }.join}"\
+	"Total Download: #{LinuxStat::PrettifyBytes.convert_decimal LinuxStat::Net.total_bytes_received}\n"\
+	"Total Upload: #{LinuxStat::PrettifyBytes.convert_decimal LinuxStat::Net.total_bytes_transmitted}"
+end
+```
+
+This will not wait in every loop for 0.5 seconds, but it will not update the cpu usage in every loop either.
+So what you will be seeing in the CPU usage in every 0.5 seconds interval.
+
+You will also see the counter increases like crazy. Which means it's not getting waited for 0.5 seconds.
+
+But the other methods doesn't have this delay, thus in this example,
+you will be able see the "Total Download" and "Total Upload" in real time,
+well as soon as the Linux kernel updates the data and ruby executes the loop.
+
+Just run the linuxstat.rb command to test what method takes what time measured in microseconds.
+
+## Note 2: Filesystem
 
 Filesystem can take arguments. By default it's '/' or the root of the system...
 
@@ -549,7 +613,7 @@ irb(main):005:0> LinuxStat::Filesystem.total(thumbdrive).fdiv(1024 ** 3).to_s <<
 => "29.305004119873047 GiB"
 ```
 
-## Note 2: ProcessInfo
+## Note 3: ProcessInfo
 
 All the methods LinuxStat::ProcessInfo can take an argument containing the Process ID of a process.
 By default it's $$ or the PID of the current process, ruby, itself.
@@ -601,7 +665,7 @@ irb(main):002:0> LinuxStat::ProcessInfo.memory(LinuxStat::Process.names.find { |
 => "467.51 MiB"
 ```
 
-## Note 3: FS
+## Note 4: FS
 
 LinuxStat::FS module gives you the raw info in Hash collected from statvfs.
 
@@ -626,7 +690,7 @@ irb(main):003:0> t = Time.now ; puts LinuxStat::FS.stat('/') ; Time.now - t
 
 To learn more about them, just run ri and the method name. To see all available methods.
 
-## Note 4: User
+## Note 5: User
 Most of the LinuxStat::User supports arguments.
 
 For example, to get a user's home by the username:
@@ -708,7 +772,7 @@ irb(main):004:0> LinuxStat::User.get_login
 
 Right, the get_login() can return an empty string. But LinuxStat::User.get_user also aliased as LinuxStat::User.get_current_user shouldn't return an empty string under most circumstances.
 
-## Note 5: PrettifyBytes
+## Note 6: PrettifyBytes
 Often times we need to work with KB, MB GB, TB, or KiB, MiB, GiB, TiB, etc.
 And we need some work to convert bytes to those units.
 Because LinuxStat provides a lot of data in bytes, and kilobytes, it's quite tedious to convert them all the time.

data/ext/fs_stat/extconf.rb

@@ -1,6 +1,10 @@
 require 'mkmf'
 
-unless (have_header('sys/statvfs.h') && have_header('ruby.h'))
+unless have_const('linux') || RbConfig::CONFIG['arch'].to_s[/linux/]
+	abort('Platform is not linux')
+end
+
+unless have_header('sys/statvfs.h') && have_header('ruby.h')
 	abort('Missing header')
 end
 

data/ext/sysconf/extconf.rb

@@ -1,6 +1,10 @@
 require 'mkmf'
 
-unless (have_header('sys/unistd.h') && have_header('ruby.h'))
+unless have_const('linux') || RbConfig::CONFIG['arch'].to_s[/linux/]
+	abort('Platform is not linux')
+end
+
+unless have_header('sys/unistd.h') && have_header('ruby.h')
 	abort('Missing header')
 end
 

data/ext/utsname/extconf.rb

@@ -1,6 +1,10 @@
 require 'mkmf'
 
-unless (have_header('sys/utsname.h') && have_header('ruby.h'))
+unless have_const('linux') || RbConfig::CONFIG['arch'].to_s[/linux/]
+	abort('Platform is not linux')
+end
+
+unless have_header('sys/utsname.h') && have_header('ruby.h')
 	abort('Missing header')
 end
 

data/lib/linux_stat/battery.rb

@@ -3,12 +3,15 @@ module LinuxStat
 		PATH = "/sys/class/power_supply/BAT0"
 
 		class << self
+			##
 			# Returns true or false based on the presence of the battery.
 			def present?
 				@@present ||= Dir.exist?(PATH)
 			end
 
+			##
 			# Returns the details of the battery.
+			#
 			# If the battery is not present it will return an empty Hash.
 			def stat
 				st = status.downcase
@@ -26,57 +29,73 @@ module LinuxStat
 				}
 			end
 
+			##
 			# Returns the model of the battery.
+			#
 			# If the battery is not present or the information isn't available it will return an empty String.
 			def model
 				return ''.freeze unless model_readable?
 				IO.read(File.join(PATH, 'model_name')).tap(&:strip!)
 			end
 
+			##
 			# Returns the manufacturer of the battery.
+			#
 			# If the battery is not present or the information is not available, it will return an empty String.
 			def manufacturer
 				return ''.freeze unless manufacturer_readable?
 				IO.read(File.join(PATH, 'manufacturer')).tap(&:strip!)
 			end
 
+			##
 			# Returns the technology of the battery.
+			#
 			# If the battery is not present or the information is not available, it will return an empty String.
 			def technology
 				return ''.freeze unless tech_readable?
 				IO.read(File.join(PATH, 'technology')).tap(&:strip!)
 			end
 
+			##
 			# Returns the status of the battery.
-			# If the battery is not present or the information is not available, it will return an empty String.
 			# The status generally includes either of the full, charging, discharging and unknown states in most cases.
+			#
+			# If the battery is not present or the information is not available, it will return an empty frozen String.
 			def status
 				return ''.freeze unless status_readable?
 				IO.read(File.join(PATH, 'status')).tap(&:strip!)
 			end
 
+			##
 			# Returns true if the battery is charging, false if the battery is not charging.
+			#
 			# If the battery is not present or the information is not available, it will return nil.
 			def charging?
 				return nil if status.empty?
 				%w(full charging unknown).each(&:freeze).include?(status.downcase)
 			end
 
+			##
 			# Returns true if the battery is discharging, false if the battery is not discharging.
+			#
 			# If the battery is not present or the information is not available, it will return nil.
 			def discharging?
 				return nil if status.empty?
 				status.downcase == 'discharging'
 			end
 
+			##
 			# Returns true if the battery status if full, false if the battery status is not full.
+			#
 			# If the battery is not present or the information is not available, it will return nil.
 			def full?
 				return nil if status.empty?
 				status.downcase == 'full'
 			end
 
+			##
 			# Returns the charge of the battery.
+			#
 			# If the battery is not present or the information is not available, it will return nil.
 			def charge
 				return nil unless charge_now_readable?

data/lib/linux_stat/bios.rb

@@ -1,7 +1,9 @@
 module LinuxStat
 	module BIOS
 		class << self
+			##
 			# Returns the model of the BIOS.
+			#
 			# If the information is not available it will return a frozen empty string.
 			#
 			# The output is also cached (memoized) ; as changing the value in runtime is unexpected.
@@ -16,7 +18,9 @@ module LinuxStat
 				end
 			end
 
+			##
 			# Returns the vendor of the BIOS.
+			#
 			# If the information is not available it will return a frozen empty string.
 			#
 			# The output is also cached (memoized) ; as changing the value in runtime is unexpected.
@@ -29,7 +33,9 @@ module LinuxStat
 				end
 			end
 
+			##
 			# Returns the version of the BIOS.
+			#
 			# If the information is not available it will return a frozen empty string.
 			#
 			# The output is also cached (memoized) ; as changing the value in runtime is unexpected.
@@ -41,7 +47,9 @@ module LinuxStat
 				end
 			end
 
+			##
 			# Returns the date of the BIOS.
+			#
 			# If the information is not available it will return a frozen empty string.
 			#
 			# The output is also cached (memoized) ; as changing the value in runtime is unexpected.

data/lib/linux_stat/cpu.rb

@@ -1,16 +1,21 @@
 module LinuxStat
 	module CPU
 		class << self
-			# stat(sleep = 1.0 / LinuxStat::Sysconf.sc_clk_tck)
+			##
+			# = stat(sleep = 1.0 / LinuxStat::Sysconf.sc_clk_tck)
+			#
 			# Where sleep is the delay to gather the data.
+			#
 			# The minimum possible value at anytime is 1.0 / LinuxStat::Sysconf.sc_clk_tck
+			#
 			# This method returns the cpu usage of all threads.
 			#
 			# The first one is aggregated CPU usage reported by the Linux kernel.
+			#
 			# And the consecutive ones are the real core usages.
 			#
 			# On a system with 4 threads, the output will be like::
-			# {0=>84.38, 1=>100.0, 2=>50.0, 3=>87.5, 4=>87.5}
+			#    {0=>84.38, 1=>100.0, 2=>50.0, 3=>87.5, 4=>87.5}
 			#
 			# If the information is not available, it will return an empty Hash
 			def stat(sleep = ticks_to_ms)
@@ -43,9 +48,13 @@ module LinuxStat
 				end
 			end
 
-			# total_usage(sleep = 1.0 / LinuxStat::Sysconf.sc_clk_tck)
+			##
+			# = total_usage(sleep = 1.0 / LinuxStat::Sysconf.sc_clk_tck)
+			#
 			# Where sleep is the delay to gather the data.
+			#
 			# The minimum possible value at anytime is 1.0 / LinuxStat::Sysconf.sc_clk_tck
+			#
 			# This method returns the cpu usage of all threads.
 			#
 			# It's like running LinuxStat::CPU.stat[0] but it's much more efficient and calculates just the aggregated usage which is available at the top of the /proc/stat file.
@@ -66,14 +75,18 @@ module LinuxStat
 				totald.-(idle_now - idle_then).fdiv(totald).*(100).round(2).abs
 			end
 
+			##
 			# Returns the total number of CPU threads.
+			#
 			# If the information isn't available, it will return 0.
 			def count
 				# CPU count can change during the program runtime
 				cpuinfo.count { |x| x.start_with?('processor') }
 			end
 
+			##
 			# Returns the model of processor.
+			#
 			# If the information isn't available, it will return en empty string.
 			#
 			# The output is also cached (memoized) ; as changing the value in runtime is unexpected.
@@ -81,7 +94,9 @@ module LinuxStat
 				@@name ||= cpuinfo.find { |x| x.start_with?('model name') }.to_s.split(?:)[-1].to_s.strip
 			end
 
+			##
 			# Returns an array with current core frequencies corresponding to the usages.
+			#
 			# If the information isn't available, it will return an empty array.
 			def cur_freq
 				@@cpu_freqs ||= Dir["/sys/devices/system/cpu/cpu[0-9]*/cpufreq/scaling_cur_freq"]
@@ -94,7 +109,9 @@ module LinuxStat
 				end
 			end
 
+			##
 			# Returns an array with max core frequencies corresponding to the usages.
+			#
 			# If the information isn't available, it will return an empty array.
 			def max_freq
 				@@max_freqs ||= Dir["/sys/devices/system/cpu/cpu[0-9]*/cpufreq/scaling_max_freq"]

data/lib/linux_stat/filesystem.rb

@@ -1,13 +1,16 @@
 module LinuxStat
 	module Filesystem
 		class << self
-			# stat(fs = '/')
+			##
+			# = stat(fs = '/')
+			#
 			# Where fs is the directory of the file system (like / or /tmp/ or /run/media/thumbdrive).
 			#
-			# It returns a Hash with the following info:
-			# 1. total size of the device (in bytes)
-			# 2. free space (in kilobytes)
-			# 3. used space (in kilobytes)
+			# * It returns a Hash with the following info:
+			#
+			#   1. total size of the device (in bytes)
+			#   2. free space (in kilobytes)
+			#   3. used space (in kilobytes)
 			#
 			# In a hash format:
 			#    {:total=>119981191168, :free=>43155574784, :used=>76825616384, :available=>43155574784}
@@ -25,8 +28,11 @@ module LinuxStat
 				}
 			end
 
-			# total(fs = '/')
+			##
+			# = total(fs = '/')
+			#
 			# Where fs is the directory of the file system (like / or /tmp/ or /run/media/thumbdrive).
+			#
 			# It returns the total size of a given disk in bytes.
 			#
 			# If the stat can't be acquired, this method will return nil.
@@ -37,10 +43,15 @@ module LinuxStat
 				s[:block_size] * s[:blocks]
 			end
 
-			# free(fs = '/')
+			##
+			# = free(fs = '/')
+			#
 			# Where fs is the directory of the file system (like / or /tmp/ or /run/media/thumbdrive).
+			#
 			# It returns the total free space in a disk in bytes.
+			#
 			# It is to be noted that free is not same as available.
+			#
 			# Free returns the size of free blocks.
 			#
 			# If the stat can't be acquired, this method will return an empty Hash.
@@ -51,8 +62,11 @@ module LinuxStat
 				s[:block_size] * s[:block_free]
 			end
 
-			# used(fs = '/')
+			##
+			# = used(fs = '/')
+			#
 			# Where fs is the directory of the file system (like / or /tmp/ or /run/media/thumbdrive).
+			#
 			# It returns the used space of a given disk in bytes.
 			#
 			# If the stat can't be acquired, this method will return nil.
@@ -63,10 +77,15 @@ module LinuxStat
 				s[:blocks].-(s[:block_free]) * s[:block_size]
 			end
 
-			# available(fs = '/')
+			##
+			# = available(fs = '/')
+			#
 			# Where fs is the directory of the file system (like / or /tmp/ or /run/media/thumbdrive).
+			#
 			# It returns the total free space in a disk in bytes.
+			#
 			# It is to be noted that free is not same as available.
+			#
 			# Available returns the size of free blocks for unpriviledged users.
 			#
 			# If the stat can't be acquired, this method will return an empty Hash.
@@ -77,7 +96,9 @@ module LinuxStat
 				s[:block_size] * s[:block_avail_unpriv]
 			end
 
-			# stat_raw(fs = '/')
+			##
+			# = stat_raw(fs = '/')
+			#
 			# Where fs is the directory of the file system (like / or /tmp/ or /run/media/thumbdrive).
 			#
 			# It returns a Hash with the following data (for example):