lib/raindrops.rb

   1 # -*- encoding: binary -*-
   2 # frozen_string_literal: false
   3 #
   4 # Each Raindrops object is a container that holds several counters.
   5 # It is internally a page-aligned, shared memory area that allows
   6 # atomic increments, decrements, assignments and reads without any
   7 # locking.
   8 #
   9 #   rd = Raindrops.new 4
  10 #   rd.incr(0, 1)   -> 1
  11 #   rd.to_ary       -> [ 1, 0, 0, 0 ]
  12 #
  13 # Unlike many classes in this package, the core Raindrops class is
  14 # intended to be portable to all reasonably modern *nix systems
  15 # supporting mmap().  Please let us know if you have portability
  16 # issues, patches or pull requests at mailto:raindrops-public@yhbt.net
  17 class Raindrops
  18
  19   # Used to represent the number of +active+ and +queued+ sockets for
  20   # a single listen socket across all threads and processes on a
  21   # machine.
  22   #
  23   # For TCP listeners, only sockets in the TCP_ESTABLISHED state are
  24   # accounted for.  For Unix domain listeners, only CONNECTING and
  25   # CONNECTED Unix domain sockets are accounted for.
  26   #
  27   # +active+ connections is the number of accept()-ed but not-yet-closed
  28   # sockets in all threads/processes sharing the given listener.
  29   #
  30   # +queued+ connections is the number of un-accept()-ed sockets in the
  31   # queue of a given listen socket.
  32   #
  33   # These stats are currently only available under \Linux
  34   class ListenStats < Struct.new(:active, :queued)
  35
  36     # the sum of +active+ and +queued+ sockets
  37     def total
  38       active + queued
  39     end
  40   end unless defined? ListenStats
  41
  42   # call-seq:
  43   #     Raindrops.new(size, io: nil)    -> raindrops object
  44   #
  45   # Initializes a Raindrops object to hold +size+ counters.  +size+ is
  46   # only a hint and the actual number of counters the object has is
  47   # dependent on the CPU model, number of cores, and page size of
  48   # the machine.  The actual size of the object will always be equal
  49   # or greater than the specified +size+.
  50   # If +io+ is provided, then the Raindrops memory will be backed by
  51   # the specified file; otherwise, it will allocate anonymous memory.
  52   # The IO object must respond to +truncate+, as this is used to set
  53   # the size of the file.
  54   # If +zero+ is provided, then the memory region is zeroed prior to
  55   # returning. This is only meaningful if +io+ is also provided; in
  56   # that case it controls whether any existing counter values in +io+
  57   # are retained (false) or whether it is entirely zeroed (true).
  58   def initialize(size, io: nil, zero: false)
  59     # This ruby wrapper exists to handle the keyword-argument handling,
  60     # which is otherwise kind of awkward in C. We delegate the keyword
  61     # arguments to the _actual_ initialize implementation as positional
  62     # args.
  63     initialize_cimpl(size, io, zero)
  64   end
  65
  66   autoload :Linux, 'raindrops/linux'
  67   autoload :Struct, 'raindrops/struct'
  68   autoload :Middleware, 'raindrops/middleware'
  69   autoload :Aggregate, 'raindrops/aggregate'
  70   autoload :LastDataRecv, 'raindrops/last_data_recv'
  71   autoload :Watcher, 'raindrops/watcher'
  72 end
  73 require 'raindrops_ext'