
Proc Utilities
**************

Helper functions for querying process and system information from the
/proc contents. Fetching information this way provides huge
performance benefits over lookups via system utilities (ps, netstat,
etc). For instance, resolving connections this way cuts the runtime by
around 90% verses the alternatives. These functions may not work on
all platforms (only Linux?).

The method for reading these files (and a little code) are borrowed
from psutil, which was written by Jay Loden, Dave Daeschler, Giampaolo
Rodola' and is under the BSD license.

**These functions are not being vended to stem users. They may change
in the future, use them at your own risk.**

Changed in version 1.3.0: Dropped the get_* prefix from several
function names. The old names still work, but are deprecated aliases.

**Module Overview:**

   is_available - checks if proc utilities can be used on this system
   system_start_time - unix timestamp for when the system started
   physical_memory - memory available on this system
   cwd - provides the current working directory for a process
   uid - provides the user id a process is running under
   memory_usage - provides the memory usage of a process
   stats - queries statistics about a process
   file_descriptors_used - number of file descriptors used by a process
   connections - provides the connections made by a process

stem.util.proc.Stat(enum)

   Types of data available via the "stats()" function.

   +----------------+-------------------------------------------------+
   | Stat           | Description                                     |
   +================+=================================================+
   | **COMMAND**    | command name under which the process is running |
   +----------------+-------------------------------------------------+
   | **CPU_UTIME**  | total user time spent on the process            |
   +----------------+-------------------------------------------------+
   | **CPU_STIME**  | total system time spent on the process          |
   +----------------+-------------------------------------------------+
   | **START_TIME** | when this process began, in unix time           |
   +----------------+-------------------------------------------------+

stem.util.proc.is_available(*args, **kwds)

   Checks if proc information is available on this platform.

   Returns:
      **True** if proc contents exist on this platform, **False**
      otherwise

stem.util.proc.system_start_time(*args, **kwds)

   Provides the unix time (seconds since epoch) when the system
   started.

   Returns:
      **float** for the unix time of when the system started

   Raises :
      **IOError** if it can't be determined

stem.util.proc.physical_memory(*args, **kwds)

   Provides the total physical memory on the system in bytes.

   Returns:
      **int** for the bytes of physical memory this system has

   Raises :
      **IOError** if it can't be determined

stem.util.proc.cwd(pid)

   Provides the current working directory for the given process.

   Parameters:
      **pid** (*int*) -- process id of the process to be queried

   Returns:
      **str** with the path of the working directory for the process

   Raises :
      **IOError** if it can't be determined

stem.util.proc.uid(pid)

   Provides the user ID the given process is running under.

   Parameters:
      **pid** (*int*) -- process id of the process to be queried

   Returns:
      **int** with the user id for the owner of the process

   Raises :
      **IOError** if it can't be determined

stem.util.proc.memory_usage(pid)

   Provides the memory usage in bytes for the given process.

   Parameters:
      **pid** (*int*) -- process id of the process to be queried

   Returns:
      **tuple** of two ints with the memory usage of the process, of
      the form **(resident_size, virtual_size)**

   Raises :
      **IOError** if it can't be determined

stem.util.proc.stats(pid, *stat_types)

   Provides process specific information. See the "Stat" enum for
   valid options.

   Parameters:
      * **pid** (*int*) -- process id of the process to be queried

      * **stat_types** (*Stat*) -- information to be provided back

   Returns:
      **tuple** with all of the requested statistics as strings

   Raises :
      **IOError** if it can't be determined

stem.util.proc.file_descriptors_used(pid)

   Provides the number of file descriptors currently being used by a
   process.

   New in version 1.3.0.

   Parameters:
      **pid** (*int*) -- process id of the process to be queried

   Returns:
      **int** of the number of file descriptors used

   Raises :
      **IOError** if it can't be determined

stem.util.proc.connections(pid)

   Queries connection related information from the proc contents. This
   provides similar results to netstat, lsof, sockstat, and other
   connection resolution utilities (though the lookup is far quicker).

   Parameters:
      **pid** (*int*) -- process id of the process to be queried

   Returns:
      A listing of connection tuples of the form **[(local_ipAddr1,
      local_port1, foreign_ipAddr1, foreign_port1, protocol), ...]**
      (addresses and protocols are strings and ports are ints)

   Raises :
      **IOError** if it can't be determined

stem.util.proc.get_system_start_time(*args, **kwds)

   Provides the unix time (seconds since epoch) when the system
   started.

   Returns:
      **float** for the unix time of when the system started

   Raises :
      **IOError** if it can't be determined

stem.util.proc.get_physical_memory(*args, **kwds)

   Provides the total physical memory on the system in bytes.

   Returns:
      **int** for the bytes of physical memory this system has

   Raises :
      **IOError** if it can't be determined

stem.util.proc.get_cwd(pid)

   Provides the current working directory for the given process.

   Parameters:
      **pid** (*int*) -- process id of the process to be queried

   Returns:
      **str** with the path of the working directory for the process

   Raises :
      **IOError** if it can't be determined

stem.util.proc.get_uid(pid)

   Provides the user ID the given process is running under.

   Parameters:
      **pid** (*int*) -- process id of the process to be queried

   Returns:
      **int** with the user id for the owner of the process

   Raises :
      **IOError** if it can't be determined

stem.util.proc.get_memory_usage(pid)

   Provides the memory usage in bytes for the given process.

   Parameters:
      **pid** (*int*) -- process id of the process to be queried

   Returns:
      **tuple** of two ints with the memory usage of the process, of
      the form **(resident_size, virtual_size)**

   Raises :
      **IOError** if it can't be determined

stem.util.proc.get_stats(pid, *stat_types)

   Provides process specific information. See the "Stat" enum for
   valid options.

   Parameters:
      * **pid** (*int*) -- process id of the process to be queried

      * **stat_types** (*Stat*) -- information to be provided back

   Returns:
      **tuple** with all of the requested statistics as strings

   Raises :
      **IOError** if it can't be determined

stem.util.proc.get_connections(pid)

   Queries connection related information from the proc contents. This
   provides similar results to netstat, lsof, sockstat, and other
   connection resolution utilities (though the lookup is far quicker).

   Parameters:
      **pid** (*int*) -- process id of the process to be queried

   Returns:
      A listing of connection tuples of the form **[(local_ipAddr1,
      local_port1, foreign_ipAddr1, foreign_port1, protocol), ...]**
      (addresses and protocols are strings and ports are ints)

   Raises :
      **IOError** if it can't be determined
