Ruby hyperctl Gem

Build Status

Table of Contents

  1. Summary
  2. Description
  3. Install
  4. Usage
  5. Versioning
  6. Support
  7. Contributing
  8. See Also

Summary

A utility for enabling/disabling hyperthreading

Description

This Gem provides a simple cli utility named hyperctl that can check the status of and [with appropriate permissions] enable/disable hyperthreading/SMT/sibling cores on Linux via the sysfs pseudo filesystem. It should be compatible with most modern Linux distributions as long as sysfs is mounted at /sysfs.

Install

via rubygems

gem install hyperctl

from git repo with bundler

bundle install
bundle exec rake install

Usage

hyperctl

Usage:
  hyperctl
  hyperctl (--enable | --disable) [--quiet]
  hyperctl --status (--enable | --disable) [--quiet]
  hyperctl -h | --help
  hyperctl --version

Options:
  --enable      Enable hyperthreading.
  --disable     Diable hyperthreading.
  --status      Report hyperthreading state.
  --quiet       Suppress stdout.
  --version     Show version.
  -h --help     Show this screen.

Exit codes

  • 0 - success
  • 1 - option parsing related error
  • 2 - system error (Eg., permission denied)
  • 3 - status does not match desired state

no options

Prints the current status of hyperthreading on the system to the stdout. Exits with 0 if no errors were encountered.

$ hyperctl
cpu0 : enabled  - hypertheading: enabled
cpu1 : enabled  - hypertheading: enabled
cpu2 : enabled  - hypertheading: enabled
cpu3 : enabled  - hypertheading: enabled
cpu4 : enabled  - hypertheading: enabled
cpu5 : enabled  - hypertheading: enabled
cpu6 : enabled  - hypertheading: enabled
cpu7 : enabled  - hypertheading: enabled

(--enable | --disable) [--quiet]

Attempt to enable or disable all hyperthread/SMT/sibling cores on the system. Exits with 0 upon success, 2 for system errors, or 3 for state change failures (unlikely).

With appropriate permissions to modify the appropriate sysfs entries:

$ sudo hyperctl --disable
cpu0 : enabled  - hypertheading: disabled
cpu1 : enabled  - hypertheading: disabled
cpu2 : enabled  - hypertheading: disabled
cpu3 : enabled  - hypertheading: disabled
cpu4 : disabled - hypertheading: disabled
cpu5 : disabled - hypertheading: disabled
cpu6 : disabled - hypertheading: disabled
cpu7 : disabled - hypertheading: disabled
$ echo $?
0

Without appropriate permissions:

$ hyperctl --disable
Permission denied @ rb_sysopen - /sys/devices/system/cpu/cpu4/online
$ echo $?
2

--status (--enable | --disable) [--quiet]

Checks the status of hyperthread/SMT/sibling cores on the system. Exits with 0 if the state matches the (--enable | --disable) option, otherwise with 3

System already in --disable state:

$ sudo hyperctl --status --disable
cpu0 : enabled  - hypertheading: disabled
cpu1 : enabled  - hypertheading: disabled
cpu2 : enabled  - hypertheading: disabled
cpu3 : enabled  - hypertheading: disabled
cpu4 : disabled - hypertheading: disabled
cpu5 : disabled - hypertheading: disabled
cpu6 : disabled - hypertheading: disabled
cpu7 : disabled - hypertheading: disabled
$ echo $?
0

System not in --enable state:

$ sudo hyperctl --status --enable
cpu0 : enabled  - hypertheading: disabled
cpu1 : enabled  - hypertheading: disabled
cpu2 : enabled  - hypertheading: disabled
cpu3 : enabled  - hypertheading: disabled
cpu4 : disabled - hypertheading: disabled
cpu5 : disabled - hypertheading: disabled
cpu6 : disabled - hypertheading: disabled
cpu7 : disabled - hypertheading: disabled
$ echo $?
3

[--quiet]

Suppresses the stdout status message. Intended for usage from scripts.

$ sudo hyperctl --status --enable --quiet
$ echo $?
3

$ sudo hyperctl --status --disable --quiet
$ echo $?
0

Versioning

This Gem is versioned according to the Semantic Versioning 2.0.0 specification.

Support

Please log tickets and issues at github

Contributing

  1. Fork it on github
  2. Make a local clone of your fork
  3. Create a topic branch. Eg, feature/mousetrap
  4. Make/commit changes
    • Commit messages should be in imperative tense
    • Check that Rspec unit tests are not broken and coverage is added for new features - bundle exec rake spec
    • Documentation of API/features is updated as appropriate in the README
  5. When the feature is complete, rebase / squash the branch history as necessary to remove "fix typo", "oops", "whitespace" and other trivial commits
  6. Push the topic branch to github
  7. Open a Pull Request (PR) from the topic branch onto parent repo's master branch

See Also