linux_stat 0.6.3 → 0.7.4

data/lib/linux_stat/process.rb

@@ -1,7 +1,9 @@
 module LinuxStat
 	module Process
 		class << self
+			##
 			# Returns the list of processes from /proc/.
+			#
 			# The return type is an Array of Integers.
 			def list
 				Dir['/proc/*'].select! { |x|
@@ -10,12 +12,15 @@ module LinuxStat
 				}.map! { |x| File.split(x)[-1].to_i }
 			end
 
+			##
 			# Counts and returns the total number of process running on the system.
+			#
 			# The return type is Integer.
 			def count
 				list.count
 			end
 
+			##
 			# Returns all the id of processes mapped with their names as a Hash.
 			def names
 				list.reduce({}) { |h, x|
@@ -27,6 +32,7 @@ module LinuxStat
 				}
 			end
 
+			##
 			# Returns all the id of processes mapped with their status as a Hash.
 			def types
 				list.reduce({}) { |h, x|
@@ -46,6 +52,7 @@ module LinuxStat
 				}
 			end
 
+			##
 			# Returns all the id of processes that are sleeping.
 			# The return type is an Array of Integers.
 			def sleeping
@@ -58,6 +65,7 @@ module LinuxStat
 				}
 			end
 
+			##
 			# Returns all the id of processes that are idle.
 			# The return type is an Array of Integers.
 			def idle
@@ -70,6 +78,7 @@ module LinuxStat
 				}
 			end
 
+			##
 			# Returns all the id of processes that are zombies.
 			# The return type is an Array of Integers.
 			def zombie
@@ -82,6 +91,7 @@ module LinuxStat
 				}
 			end
 
+			##
 			# Returns all the id of processes that are running.
 			# The return type is an Array of Integers.
 			def running

data/lib/linux_stat/process_info.rb

@@ -1,12 +1,20 @@
 module LinuxStat
 	module ProcessInfo
 		class << self
-			# total_io(pid = $$)
+			##
+			# = total_io(pid = $$)
+			#
 			# Where pid is the process ID.
+			#
 			# By default it is the id of the current process ($$)
 			#
 			# It retuns the total read/write caused by a process.
-			# The output is Hash. For example, a sample output:
+			#
+			# The output is Hash.
+			#
+			# For example:
+			#    LinuxStat::ProcessInfo.total_io
+			#
 			#    {:read_bytes=>0, :write_bytes=>0}
 			#
 			# The output is only based on the total disk IO the process has done.
@@ -28,12 +36,18 @@ module LinuxStat
 				out
 			end
 
-			# cmdline(pid = $$)
+			##
+			# = cmdline(pid = $$)
+			#
 			# Where pid is the process ID.
+			#
 			# By default it is the id of the current process ($$)
 			#
 			# It retuns the total command of the process.
-			# The output is String. For example, a sample output:
+			#
+			# The output is String. For example:
+			#    LinuxStat::ProcessInfo.cmdline
+			#
 			#    "ruby -r linux_stat -e p LinuxStat::ProcessInfo.cmdline"
 			#
 			# If the info isn't available it will return an empty frozen String.
@@ -46,12 +60,18 @@ module LinuxStat
 				_cmdline.tap(&:strip!)
 			end
 
-			# command_name(pid = $$)
+			##
+			# = command_name(pid = $$)
+			#
 			# Where pid is the process ID.
+			#
 			# By default it is the id of the current process ($$)
 			#
 			# It retuns the total command name of the process.
-			# The output is String. For example, a sample output:
+			#
+			# The output is String. For example:
+			#    LinuxStat::ProcessInfo.command_name
+			#
 			#    "ruby"
 			#
 			# If the info isn't available it will return an empty frozen String.
@@ -65,22 +85,29 @@ module LinuxStat
 				File.split(_cmdline.tap(&:strip!).split[0])[-1]
 			end
 
-			# mem_stat(pid = $$)
+			##
+			# = mem_stat(pid = $$)
+			#
 			# Where pid is the process ID.
+			#
 			# By default it is the id of the current process ($$)
 			#
 			# It retuns the memory, virtual memory, and resident memory of the process.
+			#
 			# All values are in kilobytes.
 			#
-			# The output is a Hash. For example, a sample output:
+			# The output is a Hash. For example:
+			#    LinuxStat::ProcessInfo.mem_stat
+			#
 			#    {:memory=>8515.584, :virtual_memory=>79781.888, :resident_memory=>13955.072}
 			#
-			# Note:
-			# If you need only memory usage of a process, run LinuxStat::ProcessInfo.memory(pid)
-			# If you need only virtual memory for a process, run LinuxStat::ProcessInfo.virtual_memory(pid)
-			# If you need only resident memory of a process, run LinuxStat::ProcessInfo.resident_memory(pid)
+			# * Note:
+			# 1. If you need only memory usage of a process, run LinuxStat::ProcessInfo.memory(pid)
+			# 2. If you need only virtual memory for a process, run LinuxStat::ProcessInfo.virtual_memory(pid)
+			# 3. If you need only resident memory of a process, run LinuxStat::ProcessInfo.resident_memory(pid)
 			#
 			# This method opens opens multiple files.
+			#
 			# But if you need all of the info, then running this method once is efficient.
 			#
 			# If the info isn't available it will return an empty Hash.
@@ -101,13 +128,19 @@ module LinuxStat
 				}
 			end
 
-			# memory(pid = $$)
+			##
+			# = memory(pid = $$)
+			#
 			# Where pid is the process ID.
+			#
 			# By default it is the id of the current process ($$)
 			#
 			# It retuns the memory of the process.
 			# The value is in kilobytes.
-			# The output is an Integer. For example, a sample output:
+			#
+			# The output is an Integer. For example:
+			#    LinuxStat::ProcessInfo.memory
+			#
 			#    8523.776
 			#
 			# If the info isn't available it will return nil.
@@ -119,13 +152,20 @@ module LinuxStat
 				(data[1] && data[2]) ? data[1].to_i.-(data[2].to_i).*(pagesize).fdiv(1000) : nil
 			end
 
-			# virtual_memory(pid = $$)
+			##
+			# = virtual_memory(pid = $$)
+			#
 			# Where pid is the process ID.
+			#
 			# By default it is the id of the current process ($$)
 			#
 			# It retuns the virtual memory for the process.
+			#
 			# The value is in kilobytes.
-			# The output is an Integer. For example, a sample output:
+			#
+			# The output is an Integer. For example:
+			#    LinuxStat::ProcessInfo.virtual_memory
+			#
 			#    79781.888
 			#
 			# If the info isn't available it will return nil.
@@ -137,14 +177,21 @@ module LinuxStat
 				_virtual_memory ? _virtual_memory.to_i.*(pagesize).fdiv(1000) : nil
 			end
 
-			# resident_memory(pid = $$)
+			##
+			# = resident_memory(pid = $$)
+			#
 			# Where pid is the process ID.
+			#
 			# By default it is the id of the current process ($$)
 			#
 			# It retuns the resident memory for the process.
+			#
 			# The value is in kilobytes.
-			# The output is an Integer. For example, a sample output:
-			#    13996.032
+			#
+			# The output is an Integer. For example:
+			#    LinuxStat::ProcessInfo.cpu_stat
+			#
+			#    => 13996.032
 			#
 			# If the info isn't available it will return nil.
 			def resident_memory(pid = $$)
@@ -155,40 +202,48 @@ module LinuxStat
 				_vm_rss ? _vm_rss.to_i.*(pagesize).fdiv(1000) : nil
 			end
 
-			# cpu_stat(pid: $$, sleep: 1.0 / LinuxStat::Sysconf.sc_clk_tck)
+			##
+			# = cpu_stat(pid: $$, sleep: 1.0 / LinuxStat::Sysconf.sc_clk_tck)
+			#
 			# Where pid is the process ID and sleep time is the interval between measurements.
 			#
 			# By default it is the id of the current process ($$), and sleep is LinuxStat::Sysconf.sc_clk_tck
+			#
 			# The smallest amount of available sleep time is 1.0 / LinuxStat::Sysconf.sc_clk_tck.
 			#
-			# Note 1:
-			# Do note that the sleep time can slow down your application.
-			# And it's only needed for the cpu usage calculation.
+			# * Note 1:
+			# 1. Do note that the sleep time can slow down your application.
+			# 2. And it's only needed for the cpu usage calculation.
 			#
 			# It retuns the CPU usage, threads, and the last executed CPU in Hash.
+			#
 			# For example:
-			#    {:cpu_usage=>0.0, :threads=>1, :last_executed_cpu=>1}
+			#    LinuxStat::ProcessInfo.cpu_stat
+			#
+			#    => {:cpu_usage=>0.0, :threads=>1, :last_executed_cpu=>1}
 			#
 			# But if the info isn't available, it will return an empty Hash.
 			#
-			# The :cpu_usage is in percentage. It's also divided with the number
-			# of CPU. :cpu_usage for example, will return 25.0 if the CPU count
+			# The :cpu_usage is in percentage.
+			# It's also divided with the number of CPU.
+			#
+			# :cpu_usage for example, will return 25.0 if the CPU count
 			# is 4, and the process is using 100% of a thread / core.
-			# A value of 100.0 indicates it is using 100% processing power.
+			#
+			# A value of 100.0 indicates it is using 100% processing power available to the system.
 			#
 			# The :threads returns the number of threads for the process.
 			# The value is a Integer.
 			#
-			# Note 2:
-			# If you just need the CPU usage run LinuxStat::ProcessInfo.cpu_usage(pid = $$)
-			# If you just need the threads run LinuxStat::ProcessInfo.threads(pid = $$)
-			# If you just need the last executed CPU run LinuxStat::ProcessInfo.last_executed_cpu(pid = $$)
-			# Running this method is slower and it opens multiple files at once
+			# * Note 2:
+			# 1. If you just need the CPU usage run LinuxStat::ProcessInfo.cpu_usage(pid = $$)
+			# 2. If you just need the threads run LinuxStat::ProcessInfo.threads(pid = $$)
+			# 3. If you just need the last executed CPU run LinuxStat::ProcessInfo.last_executed_cpu(pid = $$)
+			# 4. Running this method is slower and it opens multiple files at once
 			#
 			# Only use this method if you need all of the data at once, in such case, it's more efficient to use this method.
 			#
-			# The :last_executed_cpu also returns an Integer indicating
-			# the last executed cpu of the process.
+			# The :last_executed_cpu also returns an Integer indicating the last executed cpu of the process.
 			def cpu_stat(pid: $$, sleep: ticks_to_ms)
 				file = "/proc/#{pid}/stat"
 				return {} unless File.readable?(file)
@@ -221,16 +276,24 @@ module LinuxStat
 				}
 			end
 
-			# cpu_usage(pid: $$, sleep: 1.0 / LinuxStat::Sysconf.sc_clk_tck)
+			##
+			# = cpu_usage(pid: $$, sleep: 1.0 / LinuxStat::Sysconf.sc_clk_tck)
+			#
 			# Where pid is the process ID and sleep time is the interval between measurements.
 			#
 			# By default it is the id of the current process ($$), and sleep is 1.0 / LinuxStat::Sysconf.sc_clk_tck
+			#
 			# The smallest amount of available sleep time is LinuxStat::Sysconf.sc_clk_tck.
 			#
 			# It retuns the CPU usage in Float.
+			#
 			# For example:
-			#    10.0
-			# A value of 100.0 indicates it is using 100% processing power.
+			#
+			#    LinuxStat::ProcessInfo.cpu_usage
+			#
+			#    => 10.0
+			#
+			# A value of 100.0 indicates it is using 100% processing power available to the system.
 			#
 			# But if the info isn't available, it will return nil.
 			#
@@ -261,13 +324,20 @@ module LinuxStat
 				totald.-(idle2 - idle1).fdiv(totald).*(100).round(2).abs./(LinuxStat::CPU.count)
 			end
 
-			# threads(pid = $$)
+			##
+			# = threads(pid = $$)
+			#
 			# Where pid is the process ID.
+			#
 			# By default it is the id of the current process ($$)
 			#
 			# It retuns the threads for the current process in Integer.
+			#
 			# For example:
-			#    1
+			#    LinuxStat::ProcessInfo.threads
+			#
+			#    => 2
+			#
 			# But if the info isn't available, it will return nil.
 			#
 			# This method is way more efficient than running LinuxStat::ProcessInfo.cpu_stat()
@@ -275,17 +345,24 @@ module LinuxStat
 				file = "/proc/#{pid}/stat".freeze
 				return nil unless File.readable?(file)
 
-				data = IO.read(file).split[19]
+				data = IO.foreach(file, ' '.freeze).first(20)[-1]
 				data ? data.to_i : nil
 			end
 
-			# last_executed_cpu(pid = $$)
+			##
+			# = last_executed_cpu(pid = $$)
+			#
 			# Where pid is the process ID.
+			#
 			# By default it is the id of the current process ($$)
 			#
 			# It retuns the last executed CPU in Integer.
+			#
 			# For example:
-			#    2
+			#    LinuxStat::ProcessInfo.last_executed_cpu
+			#
+			#    => 2
+			#
 			# But if the info isn't available, it will return nil.
 			#
 			# This method is way more efficient than running LinuxStat::ProcessInfo.cpu_stat()
@@ -296,7 +373,9 @@ module LinuxStat
 				IO.read(file).split[38].to_i
 			end
 
-			# uid(pid = $$)
+			##
+			# = uid(pid = $$)
+			#
 			# returns the UIDs of the process as an Array of Integers.
 			#
 			# If the info isn't available it returns an empty Array.
@@ -304,7 +383,7 @@ module LinuxStat
 				file = "/proc/#{pid}/status".freeze
 				return nil unless File.readable?(file)
 
-				data = IO.readlines(file.freeze).find { |x|
+				data = IO.foreach(file.freeze).find { |x|
 					x[/Uid.*\d*/]
 				}.to_s.split.drop(1)
 
@@ -316,16 +395,19 @@ module LinuxStat
 				}
 			end
 
-			# gid(pid = $$)
+			##
+			# = gid(pid = $$)
+			#
 			# returns the GIDs of the process as an Hash containing the following data:
-			# :real, :effective, :saved_set, :filesystem_uid
 			#
-			# If the info isn't available it returns an empty Hash.
+			#    :real, :effective, :saved_set, :filesystem_uid
+			#
+			# If the info isn't available or the argument passed doesn't exist as a process ID, it will return an empty Hash.
 			def gid(pid = $$)
 				file = "/proc/#{pid}/status".freeze
 				return nil unless File.readable?(file)
 
-				data = IO.readlines(file.freeze).find { |x|
+				data = IO.foreach(file.freeze).find { |x|
 					x[/Gid.*\d*/]
 				}.split.drop(1)
 
@@ -337,20 +419,131 @@ module LinuxStat
 				}
 			end
 
-			# owner(pid = $$)
+			##
+			# = owner(pid = $$)
+			#
 			# Returns the owner of the process
 			# But if the status is not available, it will return an empty frozen String.
 			def owner(pid = $$)
 				file = "/proc/#{pid}/status".freeze
 				return ''.freeze unless File.readable?(file)
 
-				gid = IO.readlines(file.freeze).find { |x|
+				gid = IO.foreach(file.freeze).find { |x|
 					x[/Gid.*\d*/]
 				}.split.drop(1)[2].to_i
 
 				LinuxStat::User.username_by_gid(gid)
 			end
 
+			##
+			# = start_time_epoch(pid = $$)
+			#
+			# Returns the epoch time (as Integer) the process was started.
+			#
+			# For example:
+			#    LinuxStat::ProcessInfo.start_time_epoch 526
+			#
+			#    => 1608097744
+			#
+			# If the info isn't available or the argument passed doesn't exist as a process ID, it will return nil.
+			def start_time_epoch(pid = $$)
+				stat_file = "/proc/#{pid}/stat".freeze
+				uptime = "/proc/uptime".freeze
+
+				@@u_readable ||= File.readable?(uptime)
+				return nil unless @@u_readable && File.readable?(stat_file)
+
+				u = IO.foreach(uptime, ' '.freeze).next.to_f
+				st = (IO.foreach(stat_file, ' '.freeze).first(22)[-1].to_f / get_ticks)
+
+				# Getting two Time objects and dealing with floating point numbers
+				# Just to make sure the time goes monotonically
+				Time.now.-(u - st).to_i
+			end
+
+			##
+			# = start_time(pid = $$)
+			#
+			# Returns the time (as Time object) the process was started.
+			#
+			# For example:
+			#    LinuxStat::ProcessInfo.start_time 14183
+			#
+			#    => 2020-12-16 13:31:43 +0000
+			#
+			# If the info isn't available or the argument passed doesn't exist as a process ID, it will return nil.
+			#
+			# The timezone returned based on current TZ.
+			# Thus the timezone could be affected by changing the ENV['TZ'] variable.
+			#
+			# Don't trust the timezone returned by the time.
+			def start_time(pid = $$)
+				# Getting two Time objects and dealing with floating point numbers
+				# Just to make sure the time goes monotonically
+				Time.at(start_time_epoch(pid))
+			end
+
+			##
+			# = running_time(pid = $$)
+			#
+			# Returns the time (in seconds, as Float) the process is running for.
+			#
+			# For example:
+			#    LinuxStat::ProcessInfo.running_time 14183
+			#
+			#    => 1947.619999999999
+			#
+			# If the info isn't available or the argument passed doesn't exist as a process ID, it will return nil.
+			def running_time(pid = $$)
+				stat_file = "/proc/#{pid}/stat".freeze
+				uptime = "/proc/uptime".freeze
+
+				@@u_readable ||= File.readable?(uptime)
+				return nil unless @@u_readable && File.readable?(stat_file)
+
+				IO.foreach(uptime, ' '.freeze).next.to_f - (IO.read(stat_file).split[21].to_i / get_ticks)
+			end
+
+			##
+			# = state(pid = $$)
+			# Returns the state of the process as a frozen String
+			#
+			# * A process could have multiple states:
+			#
+			# 1. S => Sleeping
+			#
+			# 2. R => Running
+			#
+			# 3. I => Idle
+			#
+			# 4. Z => Zombie
+			#
+			# It returns any one of them.
+			#
+			# If the info isn't available or the argument passed doesn't exist as a process ID,
+			# it will return an empty String.
+			def state(pid = $$)
+				file = "/proc/#{pid}/stat".freeze
+				return ''.freeze unless File.readable?(file)
+				IO.foreach(file, ' '.freeze).first(3)[-1].tap(&:rstrip!).freeze
+			end
+
+			##
+			# = nice(pid = $$)
+			# Returns the nice of the process
+			#
+			# The output value is an Integer ranging from -20 to 19
+			#
+			# -20 means the process has high priority, and 19 means the process has low priority
+			#
+			# If the info isn't available or the argument passed doesn't exist as a process ID, it will return nil.
+			def nice(pid = $$)
+				file = "/proc/#{pid}/stat"
+				return nil unless File.readable?(file)
+
+				IO.foreach(file, ' ').first(19)[-1].to_i
+			end
+
 			private
 			def get_ticks
 				@@ticks ||= Sysconf.sc_clk_tck