win32-job 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 616cc46c7f759058ebeb168cb3bc4056ad7f6a45
+  data.tar.gz: 1b11d76a96473a5329595841e75385a14c6444cf
+SHA512:
+  metadata.gz: 19e1fc1b49f54627771f717ad838a013409ec3cd13f667036aaf06c9113c8de0d82f95c378a23248460eb2f14cdfb13f85cc6a9f15069b1da4d03596a97d07a3
+  data.tar.gz: 7d2bd91f2104817cd31197c8f65815af65b88449bf96a3c48604c7a6f43ec8d61980c8115beee9dc2cd14a204f6ccafe5ad0fc2e01f0fddfda63338be4ab02bd

data/CHANGES

@@ -0,0 +1,2 @@
+= 0.1.0 - 4-Feb-2014
+* Initial release.

data/MANIFEST

@@ -0,0 +1,12 @@
+* CHANGES
+* MANIFEST
+* Rakefile
+* README
+* win32-job.gemspec
+* examples\example_job.rb
+* lib\win32\job.rb
+* lib\win32\job\constants.rb
+* lib\win32\job\functions.rb
+* lib\win32\job\helper.rb
+* lib\win32\job\structs.rb
+* test\test_win32_job.rb

data/README

@@ -0,0 +1,50 @@
+== Description
+  A Ruby interface to Windows' jobs, process groups for Windows.
+
+== Installation
+  gem install win32-job
+
+== Prerequisites
+  ffi
+
+== Synopsis
+  require 'win32/job'
+  include Win32
+
+  job = Job.create('test')
+
+  j.configure_limit(
+    :breakaway_ok      => true,
+    :kill_on_job_close => true,
+    :process_memory    => 1024 * 8,
+    :process_time      => 1000
+  )
+
+  job.add_process(1234)
+  job.add_process(1235)
+
+  job.close
+
+== Future Plans
+  Add a wait method that waits for all processes to complete.
+
+== Known Issues
+  None known.
+
+  Please file any bug reports on the project page at
+  http://github.com/djberg96/win32-job
+
+== License
+  Artistic 2.0
+
+== Copyright
+  (C) 2003-2013 Daniel J. Berger
+  All Rights Reserved
+
+== Warranty
+  This package is provided "as is" and without any express or
+  implied warranties, including, without limitation, the implied
+  warranties of merchantability and fitness for a particular purpose.
+
+== Author
+  Daniel J. Berger

data/Rakefile

@@ -0,0 +1,31 @@
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+
+CLEAN.include("**/*.gem", "**/*.rbc", "**/*.rbx")
+
+namespace :gem do
+  desc 'Create the win32-job gem'
+  task :create do
+    spec = eval(IO.read('win32-job.gemspec'))
+    if Gem::VERSION < "2.0"
+      Gem::Builder.new(spec).build
+    else
+      require 'rubygems/package'
+      Gem::Package.build(spec)
+    end
+  end
+
+  desc 'Install the win32-job gem'
+  task :install => [:create] do
+    file = Dir["*.gem"].first
+    sh "gem install #{file}"
+  end
+end
+
+Rake::TestTask.new do |t|
+  t.verbose = true
+  t.warning = true
+end
+
+task :default => :test

data/examples/example_job.rb

@@ -0,0 +1,29 @@
+#######################################################################
+# example_job.rb
+#
+# Simple example script for futzing with Windows Jobs. This will fire
+# up two instances of notepad and add them to the job, then close
+# them.
+#######################################################################
+require 'win32/job'
+include Win32
+
+pid1 = Process.spawn("notepad.exe")
+pid2 = Process.spawn("notepad.exe")
+sleep 0.5
+
+j = Job.new('test')
+
+j.configure_limit(
+  :breakaway_ok      => true,
+  :kill_on_job_close => true,
+  :process_memory    => 1024 * 8,
+  :process_time      => 1000
+)
+
+j.add_process(pid1)
+j.add_process(pid2)
+
+sleep 0.5
+
+j.close # Notepad instances should terminate here, too.

data/lib/win32/job.rb

@@ -0,0 +1,509 @@
+require File.join(File.dirname(__FILE__), 'job', 'constants')
+require File.join(File.dirname(__FILE__), 'job', 'functions')
+require File.join(File.dirname(__FILE__), 'job', 'structs')
+require File.join(File.dirname(__FILE__), 'job', 'helper')
+
+# The Win32 module serves as a namespace only.
+module Win32
+
+  # The Job class encapsulates a Windows Job object.
+  class Job
+    include Windows::Constants
+    include Windows::Functions
+    include Windows::Structs
+    extend Windows::Functions
+
+    # The version of the win32-job library
+    VERSION = '0.1.0'
+
+    private
+
+    # Valid options for the configure method
+    VALID_OPTIONS = %w[
+      active_process
+      affinity
+      breakaway_ok
+      die_on_unhandled_exception
+      job_memory
+      job_time
+      kill_on_job_close
+      limit_job_time
+      limit_affinity
+      minimum_working_set
+      maximum_working_set
+      preserve_job_time
+      priority_class
+      process_memory
+      process_time
+      scheduling_class
+      silent_breakaway_ok
+    ]
+
+    public
+
+    attr_reader :job_name
+
+    alias :name :job_name
+
+    # Create a new Job object identified by +name+. If no name is provided
+    # then an anonymous job is created.
+    #
+    # If the +kill_on_close+ argument is true, all associated processes are
+    # terminated and the job object then destroys itself. Otherwise, the job
+    # object will not be destroyed until all associated processes have exited.
+    #
+    def initialize(name = nil, security = nil)
+      raise TypeError unless name.is_a?(String) if name
+
+      @job_name = name
+      @process_list = []
+      @closed = false
+
+      @job_handle = CreateJobObject(security, name)
+
+      if @job_handle == 0
+        FFI.raise_windows_error('CreateJobObject', FFI.errno)
+      end
+
+      if block_given?
+        begin
+          yield self
+        ensure
+          close
+        end
+      end
+
+      ObjectSpace.define_finalizer(self, self.class.finalize(@job_handle, @closed))
+    end
+
+    # Add process +pid+ to the job object. Process ID's added to the
+    # job are tracked via the Job#process_list accessor.
+    #
+    def add_process(pid)
+      if @process_list.size > 99
+        raise ArgumentError, "maximum number of processes reached"
+      end
+
+      phandle = OpenProcess(PROCESS_ALL_ACCESS, false, pid)
+
+      if phandle == 0
+        FFI.raise_windows_error('OpenProcess', FFI.errno)
+      end
+
+      pbool = FFI::MemoryPointer.new(:int)
+
+      IsProcessInJob(phandle, 0, pbool)
+
+      if pbool.read_int == 0
+        unless AssignProcessToJobObject(@job_handle, phandle)
+          FFI.raise_windows_error('AssignProcessToJobObject', FFI.errno)
+        end
+        @process_list << pid
+      else
+        raise ArgumentError, "pid #{pid} is already part of a job"
+      end
+
+      pid
+    end
+
+    # Close the job object.
+    #
+    def close
+      CloseHandle(@job_handle) if @job_handle
+      @closed = true
+    end
+
+    # Kill all processes associated with the job object that are
+    # associated with the current process.
+    #
+    def kill
+      unless TerminateJobObject(@job_handle, Process.pid)
+        FFI.raise_windows_error('TerminateJobObject', FFI.errno)
+      end
+
+      @process_list = []
+    end
+
+    alias terminate kill
+
+    # Set various job limits. Possible options are:
+    #
+    # * active_process => Numeric
+    #     Establishes a maximum number of simultaneously active processes
+    #     associated with the job.
+    #
+    # * affinity => Numeric
+    #     Causes all processes associated with the job to use the same
+    #     processor affinity.
+    #
+    # * breakaway_ok => Boolean
+    #     If any process associated with the job creates a child process using
+    #     the CREATE_BREAKAWAY_FROM_JOB flag while this limit is in effect, the
+    #     child process is not associated with the job.
+    #
+    # * die_on_unhandled_exception => Boolean
+    #     Forces a call to the SetErrorMode function with the SEM_NOGPFAULTERRORBOX
+    #     flag for each process associated with the job. If an exception occurs
+    #     and the system calls the UnhandledExceptionFilter function, the debugger
+    #     will be given a chance to act. If there is no debugger, the functions
+    #     returns EXCEPTION_EXECUTE_HANDLER. Normally, this will cause termination
+    #     of the process with the exception code as the exit status.
+    #
+    # * job_memory => Numeric
+    #     Causes all processes associated with the job to limit the job-wide
+    #     sum of their committed memory. When a process attempts to commit
+    #     memory that would exceed the job-wide limit, it fails. If the job
+    #     object is associated with a completion port, a
+    #     JOB_OBJECT_MSG_JOB_MEMORY_LIMIT message is sent to the completion
+    #     port.
+    #
+    # * job_time => Numeric
+    #     Establishes a user-mode execution time limit for the job.
+    #
+    # * kill_on_job_close => Boolean
+    #     Causes all processes associated with the job to terminate when the
+    #     last handle to the job is closed.
+    #
+    # * minimum_working_set_size => Numeric
+    #     Causes all processes associated with the job to use the same minimum
+    #     set size. If the job is nested, the effective working set size is the
+    #     smallest working set size in the job chain.
+    #
+    # * maximum_working_set_size => Numeric
+    #     Causes all processes associated with the job to use the same maximum
+    #     set size. If the job is nested, the effective working set size is the
+    #     smallest working set size in the job chain.
+    #
+    # * per_job_user_time_limit
+    #     The per-job user-mode execution time limit, in 100-nanosecond ticks.
+    #     The system adds the current time of the processes associated with the
+    #     job to this limit.
+    #
+    #     For example, if you set this limit to 1 minute, and the job has a
+    #     process that has accumulated 5 minutes of user-mode time, the limit
+    #     actually enforced is 6 minutes.
+    #
+    #     The system periodically checks to determine whether the sum of the
+    #     user-mode execution time for all processes is greater than this
+    #     end-of-job limit. If so all processes are terminated.
+    #
+    # * per_process_user_time_limit
+    #     The per-process user-mode execution time limit, in 100-nanosecond
+    #     ticks. The system periodically checks to determine whether each
+    #     process associated with the job has accumulated more user-mode time
+    #     than the set limit. If it has, the process is terminated.
+    #     If the job is nested, the effective limit is the most restrictive
+    #     limit in the job chain.
+    #
+    # * preserve_job_time => Boolean
+    #     Preserves any job time limits you previously set. As long as this flag
+    #     is set, you can establish a per-job time limit once, then alter other
+    #     limits in subsequent calls. This flag cannot be used with job_time.
+    #
+    # * priority_class => Numeric
+    #     Causes all processes associated with the job to use the same priority
+    #     class, e.g. ABOVE_NORMAL_PRIORITY_CLASS.
+    #
+    # * process_memory => Numeric
+    #     Causes all processes associated with the job to limit their committed
+    #     memory. When a process attempts to commit memory that would exceed
+    #     the per-process limit, it fails. If the job object is associated with
+    #     a completion port, a JOB_OBJECT_MSG_PROCESS_MEMORY_LIMIT message is
+    #     sent to the completion port. If the job is nested, the effective
+    #     memory limit is the most restrictive memory limit in the job chain.
+    #
+    # * process_time => Numeric
+    #     Establishes a user-mode execution time limit for each currently
+    #     active process and for all future processes associated with the job.
+    #
+    # * scheduling_class => Numeric
+    #     Causes all processes in the job to use the same scheduling class. If
+    #     the job is nested, the effective scheduling class is the lowest
+    #     scheduling class in the job chain.
+    #
+    # * silent_breakaway_ok => Boolean
+    #     Allows any process associated with the job to create child processes
+    #     that are not associated with the job. If the job is nested and its
+    #     immediate job object allows breakaway, the child process breaks away
+    #     from the immediate job object and from each job in the parent job chain,
+    #     moving up the hierarchy until it reaches a job that does not permit
+    #     breakaway. If the immediate job object does not allow breakaway, the
+    #     child process does not break away even if jobs in its parent job
+    #     chain allow it.
+    #
+    # * subset_affinity => Numeric
+    #     Allows processes to use a subset of the processor affinity for all
+    #     processes associated with the job.
+    #--
+    # The options are based on the LimitFlags of the
+    # JOBOBJECT_BASIC_LIMIT_INFORMATION struct.
+    #
+    def configure_limit(options = {})
+      unless options.is_a?(Hash)
+        raise TypeError, "argument to configure must be a hash"
+      end
+
+      # Validate options
+      options.each{ |key,value|
+        unless VALID_OPTIONS.include?(key.to_s.downcase)
+          raise ArgumentError, "invalid option '#{key}'"
+        end
+      }
+
+      flags  = 0
+      struct = JOBOBJECT_EXTENDED_LIMIT_INFORMATION.new
+
+      if options[:active_process]
+        flags |= JOB_OBJECT_LIMIT_ACTIVE_PROCESS
+        struct[:BasicInformatin][:ActiveProcessLimit] = options[:active_process]
+      end
+
+      if options[:affinity]
+        flags |= JOB_OBJECT_LIMIT_AFFINITY
+        struct[:BasicLimitInformation][:Affinity] = options[:affinity]
+      end
+
+      if options[:breakaway_ok]
+        flags |= JOB_OBJECT_LIMIT_BREAKAWAY_OK
+      end
+
+      if options[:die_on_unhandled_exception]
+        flags |= JOB_OBJECT_LIMIT_DIE_ON_UNHANDLED_EXCEPTION
+      end
+
+      if options[:job_memory]
+        flags |= JOB_OBJECT_LIMIT_JOB_MEMORY
+        struct[:JobMemoryLimit] = options[:job_memory]
+      end
+
+      if options[:per_job_user_time_limit]
+        flags |= JOB_OBJECT_LIMIT_JOB_TIME
+        struct[:BasicLimitInformation][:PerJobUserTimeLimit][:QuadPart] = options[:per_job_user_time_limit]
+      end
+
+      if options[:kill_on_job_close]
+        flags |= JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE
+      end
+
+      if options[:preserve_job_time]
+        flags |= JOB_OBJECT_LIMIT_PRESERVE_JOB_TIME
+      end
+
+      if options[:priority_class]
+        flags |= JOB_OBJECT_LIMIT_PRIORITY_CLASS
+        struct[:BasicLimitInformation][:PriorityClass] = options[:priority_class]
+      end
+
+      if options[:process_memory]
+        flags |= JOB_OBJECT_LIMIT_PROCESS_MEMORY
+        struct[:ProcessMemoryLimit] = options[:process_memory]
+      end
+
+      if options[:process_time]
+        flags |= JOB_OBJECT_LIMIT_PROCESS_TIME
+        struct[:BasicLimitInformation][:PerProcessUserTimeLimit][:QuadPart] = options[:process_time]
+      end
+
+      if options[:scheduling_class]
+        flags |= JOB_OBJECT_LIMIT_SCHEDULING_CLASS
+        struct[:BasicLimitInformation][:SchedulingClass] = options[:scheduling_class]
+      end
+
+      if options[:silent_breakaway_ok]
+        flags |= JOB_OBJECT_LIMIT_SILENT_BREAKAWAY_OK
+      end
+
+      if options[:subset_affinity]
+        flags |= JOB_OBJECT_LIMIT_SUBSET_AFFINITY | JOB_OBJECT_LIMIT_AFFINITY
+      end
+
+      if options[:minimum_working_set_size]
+        flags |= JOB_OBJECT_LIMIT_WORKINGSET
+        struct[:BasicLimitInformation][:MinimumWorkingSetSize] = options[:minimum_working_set_size]
+      end
+
+      if options[:maximum_working_set_size]
+        flags |= JOB_OBJECT_LIMIT_WORKINGSET
+        struct[:BasicLimitInformation][:MaximumWorkingSetSize] = options[:maximum_working_set_size]
+      end
+
+      struct[:BasicLimitInformation][:LimitFlags] = flags
+
+      bool = SetInformationJobObject(
+        @job_handle,
+        JobObjectExtendedLimitInformation,
+        struct,
+        struct.size
+      )
+
+      unless bool
+        FFI.raise_windows_error('SetInformationJobObject', FFI.errno)
+      end
+
+      options
+    end
+
+    # Return a list of process ids that are part of the job.
+    #
+    def process_list
+      info = JOBOBJECT_BASIC_PROCESS_ID_LIST.new
+
+      bool = QueryInformationJobObject(
+        @job_handle,
+        JobObjectBasicProcessIdList,
+        info,
+        info.size,
+        nil
+      )
+
+      unless bool
+        FFI.raise_windows_error('QueryInformationJobObject', FFI.errno)
+      end
+
+      info[:ProcessIdList].to_a.select{ |n| n != 0 }
+    end
+
+    # Returns an AccountInfoStruct that shows various job accounting
+    # information, such as total user time, total kernel time, the
+    # total number of processes, and so on.
+    #
+    def account_info
+      info = JOBOBJECT_BASIC_AND_IO_ACCOUNTING_INFORMATION.new
+
+      bool = QueryInformationJobObject(
+        @job_handle,
+        JobObjectBasicAndIoAccountingInformation,
+        info,
+        info.size,
+        nil
+      )
+
+      unless bool
+        FFI.raise_windows_error('QueryInformationJobObject', FFI.errno)
+      end
+
+      struct = AccountInfo.new(
+        info[:BasicInfo][:TotalUserTime][:QuadPart],
+        info[:BasicInfo][:TotalKernelTime][:QuadPart],
+        info[:BasicInfo][:ThisPeriodTotalUserTime][:QuadPart],
+        info[:BasicInfo][:ThisPeriodTotalKernelTime][:QuadPart],
+        info[:BasicInfo][:TotalPageFaultCount],
+        info[:BasicInfo][:TotalProcesses],
+        info[:BasicInfo][:ActiveProcesses],
+        info[:BasicInfo][:TotalTerminatedProcesses],
+        info[:IoInfo][:ReadOperationCount],
+        info[:IoInfo][:WriteOperationCount],
+        info[:IoInfo][:OtherOperationCount],
+        info[:IoInfo][:ReadTransferCount],
+        info[:IoInfo][:WriteTransferCount],
+        info[:IoInfo][:OtherTransferCount]
+      )
+
+      struct
+    end
+
+    # Return limit information for the process group.
+    #
+    def limit_info
+      info = JOBOBJECT_EXTENDED_LIMIT_INFORMATION.new
+
+      bool = QueryInformationJobObject(
+        @job_handle,
+        JobObjectExtendedLimitInformation,
+        info,
+        info.size,
+        nil
+      )
+
+      unless bool
+        FFI.raise_windows_error('QueryInformationJobObject', FFI.errno)
+      end
+
+      struct = LimitInfo.new(
+        info[:BasicLimitInformation][:PerProcessUserTimeLimit][:QuadPart],
+        info[:BasicLimitInformation][:PerJobUserTimeLimit][:QuadPart],
+        info[:BasicLimitInformation][:LimitFlags],
+        info[:BasicLimitInformation][:MinimumWorkingSetSize],
+        info[:BasicLimitInformation][:MaximumWorkingSetSize],
+        info[:BasicLimitInformation][:ActiveProcessLimit],
+        info[:BasicLimitInformation][:Affinity],
+        info[:BasicLimitInformation][:PriorityClass],
+        info[:BasicLimitInformation][:SchedulingClass],
+        info[:IoInfo][:ReadOperationCount],
+        info[:IoInfo][:WriteOperationCount],
+        info[:IoInfo][:OtherOperationCount],
+        info[:IoInfo][:ReadTransferCount],
+        info[:IoInfo][:WriteTransferCount],
+        info[:IoInfo][:OtherTransferCount],
+        info[:ProcessMemoryLimit],
+        info[:JobMemoryLimit],
+        info[:PeakProcessMemoryUsed],
+        info[:PeakJobMemoryUsed]
+      )
+
+      struct
+    end
+
+    # Waits for the processes in the job to terminate.
+    #--
+    # See http://blogs.msdn.com/b/oldnewthing/archive/2013/04/05/10407778.aspx
+    #
+    # TODO: Fix. I'm not sure this approach is feasible without the processes
+    # having been created in a suspended state.
+    #
+=begin
+    def wait
+      io_port = CreateIoCompletionPort(INVALID_HANDLE_VALUE, 0, 0, 1)
+
+      if io_port == 0
+        FFI.raise_windows_error('CreateIoCompletionPort', FFI.errno)
+      end
+
+      port = JOBOBJECT_ASSOCIATE_COMPLETION_PORT.new
+      port[:CompletionKey] = @job_handle
+      port[:CompletionPort] = io_port
+
+      bool = SetInformationJobObject(
+        @job_handle,
+        JobObjectAssociateCompletionPortInformation,
+        port,
+        port.size
+      )
+
+      FFI.raise_windows_error('SetInformationJobObject', FFI.errno) unless bool
+
+      @process_list.each{ |pid|
+        handle = OpenProcess(PROCESS_SET_QUOTA|PROCESS_TERMINATE, false, pid)
+
+        FFI.raise_windows_error('OpenProcess', FFI.errno) unless handle
+
+        # BUG: I get access denied errors here.
+        unless AssignProcessToJobObject(@job_handle, handle)
+          FFI.raise_windows_error('AssignProcessToJobObject', FFI.errno)
+        end
+
+        # TODO: Do I need to get the thread handle and explicitly close it?
+
+        CloseHandle(handle)
+
+        olap  = OVERLAPPED.new
+        bytes = FFI::MemoryPointer.new(:ulong)
+        ckey  = FFI::MemoryPointer.new(:uintptr_t)
+
+        while GetQueuedCompletionPort(io_port, bytes, ckey, olap, INFINITE) &&
+          !(ckey.read_pointer.to_i == @job_handle && ccode == JOB_OBJECT_MSG_ACTIVE_PROCESS_ZERO)
+          sleep 0.1
+        end
+      }
+    end
+=end
+
+    private
+
+    # Automatically close job object when it goes out of scope.
+    #
+    def self.finalize(handle, closed)
+      proc{ CloseHandle(handle) unless closed }
+    end
+  end
+end

data/lib/win32/job/constants.rb

@@ -0,0 +1,64 @@
+require 'ffi'
+
+module Windows
+  module Constants
+    private
+
+    JobObjectBasicAccountingInformation = 1
+    JobObjectBasicLimitInformation = 2
+    JobObjectBasicProcessIdList = 3
+    JobObjectBasicUIRestrictions = 4
+    JobObjectSecurityLimitInformation = 5
+    JobObjectEndOfJobTimeInformation = 6
+    JobObjectAssociateCompletionPortInformation = 7
+    JobObjectBasicAndIoAccountingInformation = 8
+    JobObjectExtendedLimitInformation = 9
+    JobObjectGroupInformation = 11
+    JobObjectNotificationLimitInformation = 12
+    JobObjectLimitViolationInformation = 13
+    JobObjectGroupInformationEx = 14
+    JobObjectCpuRateControlInformation = 15
+
+    PROCESS_ALL_ACCESS = 0x1F0FFF
+    PROCESS_SET_QUOTA = 0x0100
+    PROCESS_TERMINATE = 0x0001
+    SYNCHRONIZE = 0x00100000
+
+    INFINITE = 0xFFFFFFFF
+
+    INVALID_HANDLE_VALUE = FFI::Pointer.new(-1).address
+
+    JOB_OBJECT_LIMIT_ACTIVE_PROCESS = 0x00000008
+    JOB_OBJECT_LIMIT_AFFINITY = 0x00000010
+    JOB_OBJECT_LIMIT_BREAKAWAY_OK = 0x00000800
+    JOB_OBJECT_LIMIT_DIE_ON_UNHANDLED_EXCEPTION = 0x00000400
+    JOB_OBJECT_LIMIT_JOB_MEMORY = 0x00000200
+    JOB_OBJECT_LIMIT_JOB_TIME = 0x00000004
+    JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE = 0x00002000
+    JOB_OBJECT_LIMIT_PRESERVE_JOB_TIME = 0x00000040
+    JOB_OBJECT_LIMIT_PRIORITY_CLASS = 0x00000020
+    JOB_OBJECT_LIMIT_PROCESS_MEMORY = 0x00000100
+    JOB_OBJECT_LIMIT_PROCESS_TIME = 0x00000002
+    JOB_OBJECT_LIMIT_SCHEDULING_CLASS = 0x00000080
+    JOB_OBJECT_LIMIT_SILENT_BREAKAWAY_OK = 0x00001000
+    JOB_OBJECT_LIMIT_SUBSET_AFFINITY = 0x00004000
+    JOB_OBJECT_LIMIT_WORKINGSET = 0x00000001
+
+    JOB_OBJECT_MSG_ACTIVE_PROCESS_ZERO = 4
+
+    WAIT_ABANDONED     = 0x00000080
+    WAIT_IO_COMPLETION = 0x000000C0
+    WAIT_OBJECT_0      = 0x00000000
+    WAIT_TIMEOUT       = 0x00000102
+    WAIT_FAILED        = 0xFFFFFFFF
+
+    public
+
+    ABOVE_NORMAL_PRIORITY_CLASS = 0x00008000
+    BELOW_NORMAL_PRIORITY_CLASS = 0x00004000
+    HIGH_PRIORITY_CLASS         = 0x00000080
+    IDLE_PRIORITY_CLASS         = 0x00000040
+    NORMAL_PRIORITY_CLASS       = 0x00000020
+    REALTIME_PRIORITY_CLASS     = 0x00000100
+  end
+end

data/lib/win32/job/functions.rb

@@ -0,0 +1,25 @@
+require 'ffi'
+
+module Windows
+  module Functions
+    extend FFI::Library
+    ffi_lib :kernel32
+
+    typedef :uintptr_t, :handle
+    typedef :ulong, :dword
+
+    attach_function :AssignProcessToJobObject, [:handle, :handle], :bool
+    attach_function :CloseHandle, [:handle], :bool
+    attach_function :CreateJobObject, :CreateJobObjectA, [:pointer, :string], :handle
+    attach_function :CreateIoCompletionPort, [:handle, :handle, :uintptr_t, :dword], :handle
+    attach_function :GetQueuedCompletionStatus, [:handle, :pointer, :pointer, :pointer, :dword], :bool
+    attach_function :IsProcessInJob, [:handle, :handle, :pointer], :bool
+    attach_function :OpenProcess, [:dword, :bool, :dword], :handle
+    attach_function :OpenJobObject, :OpenJobObjectA, [:dword, :bool, :string], :handle
+    attach_function :QueryInformationJobObject, [:handle, :int, :pointer, :dword, :pointer], :bool
+    attach_function :ResumeThread, [:handle], :dword
+    attach_function :SetInformationJobObject, [:handle, :int, :pointer, :dword], :bool
+    attach_function :TerminateJobObject, [:handle, :uint], :bool
+    attach_function :WaitForSingleObjectEx, [:handle, :dword, :bool], :dword
+  end
+end

data/lib/win32/job/helper.rb

@@ -0,0 +1,26 @@
+require 'ffi'
+
+module FFI
+  extend FFI::Library
+
+  ffi_lib :kernel32
+
+  attach_function :FormatMessage, :FormatMessageA,
+    [:ulong, :pointer, :ulong, :ulong, :pointer, :ulong, :pointer], :ulong
+
+  def win_error(function, err=FFI.errno)
+    flags = 0x00001000 | 0x00000200
+    buf = FFI::MemoryPointer.new(:char, 1024)
+
+    FormatMessage(flags, nil, err , 0x0409, buf, 1024, nil)
+
+    function + ': ' + buf.read_string.strip
+  end
+
+  def raise_windows_error(function, err=FFI.errno)
+    raise SystemCallError.new(win_error(function, err), err)
+  end
+
+  module_function :win_error
+  module_function :raise_windows_error
+end

data/lib/win32/job/structs.rb

@@ -0,0 +1,175 @@
+require 'ffi'
+
+module Windows
+  module Structs
+    extend FFI::Library
+
+    typedef :uintptr_t, :handle
+    typedef :ulong, :dword
+    typedef :ushort, :word
+
+    class LARGE_INTEGER < FFI::Union
+      layout(:QuadPart, :long_long)
+    end
+
+    class JOBOBJECT_BASIC_PROCESS_ID_LIST < FFI::Struct
+      layout(
+        :NumberOfAssignedProcesses, :ulong,
+        :NumberOfProcessIdsInList, :ulong,
+        :ProcessIdList, [:uintptr_t, 100] # Limit 100 processes per job (?)
+      )
+    end
+
+    class JOBOBJECT_BASIC_ACCOUNTING_INFORMATION < FFI::Struct
+      layout(
+        :TotalUserTime, LARGE_INTEGER,
+        :TotalKernelTime, LARGE_INTEGER,
+        :ThisPeriodTotalUserTime, LARGE_INTEGER,
+        :ThisPeriodTotalKernelTime, LARGE_INTEGER,
+        :TotalPageFaultCount, :ulong,
+        :TotalProcesses, :ulong,
+        :ActiveProcesses, :ulong,
+        :TotalTerminatedProcesses, :ulong
+      )
+    end
+
+    class IO_COUNTERS < FFI::Struct
+      layout(
+        :ReadOperationCount, :ulong_long,
+        :WriteOperationCount, :ulong_long,
+        :OtherOperationCount, :ulong_long,
+        :ReadTransferCount, :ulong_long,
+        :WriteTransferCount, :ulong_long,
+        :OtherTransferCount, :ulong_long
+      )
+    end
+
+    class JOBOBJECT_BASIC_AND_IO_ACCOUNTING_INFORMATION < FFI::Struct
+      layout(
+        :BasicInfo, JOBOBJECT_BASIC_ACCOUNTING_INFORMATION,
+        :IoInfo, IO_COUNTERS
+      )
+    end
+
+    class JOBOBJECT_BASIC_LIMIT_INFORMATION < FFI::Struct
+      layout(
+        :PerProcessUserTimeLimit, LARGE_INTEGER,
+        :PerJobUserTimeLimit, LARGE_INTEGER,
+        :LimitFlags, :ulong,
+        :MinimumWorkingSetSize, :size_t,
+        :MaximumWorkingSetSize, :size_t,
+        :ActiveProcessLimit, :ulong,
+        :Affinity, :uintptr_t,
+        :PriorityClass, :ulong,
+        :SchedulingClass, :ulong
+      )
+    end
+
+    class JOBOBJECT_EXTENDED_LIMIT_INFORMATION < FFI::Struct
+      layout(
+        :BasicLimitInformation, JOBOBJECT_BASIC_LIMIT_INFORMATION,
+        :IoInfo, IO_COUNTERS,
+        :ProcessMemoryLimit, :size_t,
+        :JobMemoryLimit, :size_t,
+        :PeakProcessMemoryUsed, :size_t,
+        :PeakJobMemoryUsed, :size_t
+      )
+    end
+
+    class JOBOBJECT_ASSOCIATE_COMPLETION_PORT < FFI::Struct
+      layout(:CompletionKey, :uintptr_t, :CompletionPort, :handle)
+    end
+
+    class SECURITY_ATTRIBUTES < FFI::Struct
+      layout(
+        :nLength, :ulong,
+        :lpSecurityDescriptor, :pointer,
+        :bInheritHandle, :bool
+      )
+    end
+
+    class PROCESS_INFORMATION < FFI::Struct
+      layout(
+        :hProcess, :handle,
+        :hThread, :handle,
+        :dwProcessId, :dword,
+        :dwThreadId, :dword
+      )
+    end
+
+    class STARTUPINFO < FFI::Struct
+      layout(
+        :cb, :ulong,
+        :lpReserved, :string,
+        :lpDesktop, :string,
+        :lpTitle, :string,
+        :dwX, :dword,
+        :dwY, :dword,
+        :dwXSize, :dword,
+        :dwYSize, :dword,
+        :dwXCountChars, :dword,
+        :dwYCountChars, :dword,
+        :dwFillAttribute, :dword,
+        :dwFlags, :dword,
+        :wShowWindow, :word,
+        :cbReserved2, :word,
+        :lpReserved2, :pointer,
+        :hStdInput, :handle,
+        :hStdOutput, :handle,
+        :hStdError, :handle
+      )
+    end
+
+    # I'm assuming the anonymous struct for the internal union here.
+    class Overlapped < FFI::Struct
+      layout(
+        :Internal, :ulong,
+        :InternalHigh, :ulong,
+        :Offset, :ulong,
+        :OffsetHigh, :ulong,
+        :hEvent, :ulong
+      )
+    end
+
+    # Ruby Structs
+
+    AccountInfo = Struct.new('AccountInfo',
+      :total_user_time,
+      :total_kernel_time,
+      :this_period_total_user_time,
+      :this_period_total_kernel_time,
+      :total_page_fault_count,
+      :total_processes,
+      :active_processes,
+      :total_terminated_processes,
+      :read_operation_count,
+      :write_operation_count,
+      :other_operation_count,
+      :read_transfer_count,
+      :write_transfer_count,
+      :other_transfer_count
+    )
+
+    LimitInfo = Struct.new('LimitInfo',
+      :per_process_user_time_limit,
+      :per_job_user_time_limit,
+      :limit_flags,
+      :minimum_working_set_size,
+      :maximum_working_set_size,
+      :active_process_limit,
+      :affinity,
+      :priority_class,
+      :scheduling_class,
+      :read_operation_count,
+      :write_operation_count,
+      :other_operation_count,
+      :read_transfer_count,
+      :write_transfer_count,
+      :other_transfer_count,
+      :process_memory_limit,
+      :job_memory_limit,
+      :peak_process_memory_used,
+      :peek_job_memory_used
+    )
+  end
+end

data/test/test_win32_job.rb

@@ -0,0 +1,126 @@
+#######################################################################
+# test_win32_job.rb
+#
+# Test suite for the win32-job library. You should run these tests
+# via the "rake test" command.
+#######################################################################
+require 'test-unit'
+require 'win32/job'
+
+class TC_Win32_Job < Test::Unit::TestCase
+  def setup
+    @name = 'ruby_xxxxxx'
+    @job = Win32::Job.new(@name)
+    @pid = Process.spawn('notepad')
+  end
+
+  test "version number is what we expect" do
+    assert_equal('0.1.0', Win32::Job::VERSION)
+  end
+
+  test "constructor argument may be omitted" do
+    assert_nothing_raised{ Win32::Job.new }
+  end
+
+  test "constructor accepts a name for the job" do
+    assert_nothing_raised{ Win32::Job.new(@name) }
+  end
+
+  test "argument to constructor must be a string" do
+    assert_raise(TypeError){ Win32::Job.new(1) }
+  end
+
+  test "job_name basic functionality" do
+    assert_respond_to(@job, :job_name)
+    assert_nothing_raised{ @job.job_name }
+    assert_kind_of(String, @job.job_name)
+  end
+
+  test "job_name is read-only" do
+    assert_raise(NoMethodError){ @job.job_name = 'foo' }
+  end
+
+  test "name is an alias for job_name" do
+    assert_alias_method(@job, :name, :job_name)
+  end
+
+  test "close basic functionality" do
+    assert_respond_to(@job, :close)
+    assert_nothing_raised{ @job.close }
+  end
+
+  test "calling close multiple times has no effect" do
+    assert_nothing_raised{ @job.close }
+    assert_nothing_raised{ @job.close }
+    assert_nothing_raised{ @job.close }
+  end
+
+  test "close method does not accept any arguments" do
+    assert_raise(ArgumentError){ @job.close(1) }
+  end
+
+  test "add_process basic functionality" do
+    assert_respond_to(@job, :add_process)
+  end
+
+  test "add_process works as expected" do
+    assert_nothing_raised{ @job.add_process(@pid) }
+  end
+
+  test "add process requires a single argument" do
+    assert_raise(ArgumentError){ @job.add_process }
+  end
+
+  test "kill basic functionality" do
+    assert_respond_to(@job, :kill)
+  end
+
+  test "kill works as expected" do
+    @job.add_process(@pid)
+    assert_equal(@pid, @job.process_list.first)
+    assert_nothing_raised{ @job.kill }
+    assert_true(@job.process_list.empty?)
+  end
+
+  test "terminate is an alias for kill" do
+    assert_alias_method(@job, :kill, :terminate)
+  end
+
+  test "configure_limit basic functionality" do
+    assert_nothing_raised{ @job.configure_limit }
+  end
+
+  test "configure_limit works as expected" do
+    assert_nothing_raised{
+      @job.configure_limit(
+        :breakaway_ok      => true,
+        :kill_on_job_close => true,
+        :process_memory    => 1024 * 8,
+        :process_time      => 1000
+      )
+    }
+  end
+
+  test "configure_limit raises an error if it detects an invalid option" do
+    assert_raise(ArgumentError){ @job.configure_limit(:bogus => 1) }
+  end
+
+  test "priority constants are defined" do
+    assert_not_nil(Win32::Job::ABOVE_NORMAL_PRIORITY_CLASS)
+    assert_not_nil(Win32::Job::BELOW_NORMAL_PRIORITY_CLASS)
+    assert_not_nil(Win32::Job::HIGH_PRIORITY_CLASS)
+    assert_not_nil(Win32::Job::IDLE_PRIORITY_CLASS)
+    assert_not_nil(Win32::Job::NORMAL_PRIORITY_CLASS)
+    assert_not_nil(Win32::Job::REALTIME_PRIORITY_CLASS)
+  end
+
+  def teardown
+    @name = nil
+
+    @job.close
+    @job = nil
+
+    Process.kill(9, @pid) rescue nil
+    @pid = nil
+  end
+end

data/win32-job.gemspec

@@ -0,0 +1,28 @@
+require 'rubygems'
+
+Gem::Specification.new do |spec|
+  spec.name      = 'win32-job'
+  spec.version   = '0.1.0'
+  spec.author    = 'Daniel J. Berger'
+  spec.license   = 'Artistic 2.0'
+  spec.email     = 'djberg96@gmail.com'
+  spec.homepage  = 'http://github.com/djberg96/win32-job'
+  spec.summary   = 'Interface for Windows jobs (process groups)'
+  spec.test_file = 'test/test_win32_job.rb'
+  spec.files     = Dir['**/*'].reject{ |f| f.include?('git') }
+
+  spec.extra_rdoc_files  = ['README', 'CHANGES', 'MANIFEST']
+  spec.rubyforge_project = 'win32utils'
+  spec.required_ruby_version = '> 1.9.1'
+
+  spec.add_dependency('ffi')
+
+  spec.add_development_dependency('rake')
+  spec.add_development_dependency('test-unit')
+
+  spec.description = <<-EOF
+    The win32-job library provides an interface for jobs (process groups)
+    on MS Windows. This allows you to apply various limits and behavior to
+    groups of processes on Windows.
+  EOF
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: win32-job
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Daniel J. Berger
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-02-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: test-unit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |2
+      The win32-job library provides an interface for jobs (process groups)
+      on MS Windows. This allows you to apply various limits and behavior to
+      groups of processes on Windows.
+email: djberg96@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README
+- CHANGES
+- MANIFEST
+files:
+- CHANGES
+- examples/example_job.rb
+- lib/win32/job/constants.rb
+- lib/win32/job/functions.rb
+- lib/win32/job/helper.rb
+- lib/win32/job/structs.rb
+- lib/win32/job.rb
+- MANIFEST
+- Rakefile
+- README
+- test/test_win32_job.rb
+- win32-job-0.1.0.gem
+- win32-job.gemspec
+homepage: http://github.com/djberg96/win32-job
+licenses:
+- Artistic 2.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>'
+    - !ruby/object:Gem::Version
+      version: 1.9.1
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: win32utils
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: Interface for Windows jobs (process groups)
+test_files:
+- test/test_win32_job.rb