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

   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

   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

   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=None, user=None)

   Queries connections from the proc contents. This matches netstat,
   lsof, and friends but is much faster. If no **pid** or **user** are
   provided this provides all present connections.

   Parameters:
      * **pid** (*int*) – pid to provide connections for

      * **user** (*str*) – username to look up connections for

   Returns:
      **list** of "Connection" instances

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

stem.util.proc.get_system_start_time

   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

   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=None, user=None)

   Queries connections from the proc contents. This matches netstat,
   lsof, and friends but is much faster. If no **pid** or **user** are
   provided this provides all present connections.

   Parameters:
      * **pid** (*int*) – pid to provide connections for

      * **user** (*str*) – username to look up connections for

   Returns:
      **list** of "Connection" instances

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