semian 0.6.2 → 0.7.0

data/ext/semian/sysv_semaphores.h

@@ -16,7 +16,8 @@ and functions associated directly weth semops.
 #include <ruby/util.h>
 #include <ruby/io.h>
 
-#include <types.h>
+#include "types.h"
+#include "tickets.h"
 
 // Defines for ruby threading primitives
 #if defined(HAVE_RB_THREAD_CALL_WITHOUT_GVL) && defined(HAVE_RUBY_THREAD_H)
@@ -32,15 +33,45 @@ typedef VALUE (*my_blocking_fn_t)(void*);
 // Time to wait for timed ops to complete
 #define INTERNAL_TIMEOUT 5 /* seconds */
 
+// Time to wait while checking if semaphore has been initialized
+#define INIT_WAIT 10 /* microseconds */
+
+// Helper definition to prevent magic number for conversion of microseconds to seconds
+#define MICROSECONDS_IN_SECOND 1000000
+
+// Here we define an enum value and string representation of each semaphore
+// This allows us to key the sem value and string rep in sync easily
+// utilizing pre-processor macros.
+// If you're unfamiliar with this pattern, this is using "x macros"
+//   SI_SEM_LOCK                metadata lock to act as a mutex, ensuring thread-safety for updating other semaphores
+//   SI_SEM_TICKETS             semaphore for the tickets currently issued
+//   SI_SEM_CONFIGURED_TICKETS  semaphore to track the desired number of tickets available for issue
+//   SI_SEM_REGISTERED_WORKERS  semaphore for the number of workers currently registered
+//   SI_NUM_SEMAPHORES          always leave this as last entry for count to be accurate
+#define FOREACH_SEMINDEX(SEMINDEX) \
+        SEMINDEX(SI_SEM_LOCK)   \
+        SEMINDEX(SI_SEM_TICKETS)   \
+        SEMINDEX(SI_SEM_CONFIGURED_TICKETS)  \
+        SEMINDEX(SI_SEM_REGISTERED_WORKERS)  \
+        SEMINDEX(SI_NUM_SEMAPHORES)  \
+
+#define GENERATE_ENUM(ENUM) ENUM,
+#define GENERATE_STRING(STRING) #STRING,
+
+// Generate enum for sem indices
+enum SEMINDEX_ENUM {
+    FOREACH_SEMINDEX(GENERATE_ENUM)
+};
+
 VALUE eSyscall, eTimeout, eInternal;
 
 // Helper for syscall verbose debugging
 void
 raise_semian_syscall_error(const char *syscall, int error_num);
 
-// Genurates a unique key for the semaphore from the resource id
-key_t
-generate_key(const char *name);
+// Initialize the sysv semaphore structure
+void
+initialize_semaphore_set(semian_resource_t* res, const char* id_str, long permissions, int tickets, double quota);
 
 // Set semaphore UNIX octal permissions
 void
@@ -57,7 +88,7 @@ perform_semop(int sem_id, short index, short op, short flags, struct timespec *t
 
 // Retrieve the current number of tickets in a semaphore by its semaphore index
 int
-get_max_tickets(int sem_id);
+get_sem_val(int sem_id, int sem_index);
 
 // Obtain an exclusive lock on the semaphore set critical section
 void
@@ -75,4 +106,17 @@ get_semaphore(int key);
 void *
 acquire_semaphore_without_gvl(void *p);
 
+#ifdef DEBUG
+static inline void
+print_sem_vals(int sem_id)
+{
+  printf("lock %d, tickets: %d configured: %d, registered workers %d\n",
+   get_sem_val(sem_id, SI_SEM_LOCK),
+   get_sem_val(sem_id, SI_SEM_TICKETS),
+   get_sem_val(sem_id, SI_SEM_CONFIGURED_TICKETS),
+   get_sem_val(sem_id, SI_SEM_REGISTERED_WORKERS)
+  );
+}
+#endif
+
 #endif // SEMIAN_SEMSET_H

data/ext/semian/tickets.c

@@ -1,72 +1,82 @@
-#include <tickets.h>
+#include "tickets.h"
 
-VALUE
+// Update the ticket count for static ticket tracking
+static VALUE
+update_ticket_count(update_ticket_count_t *tc);
+
+static int
+calculate_quota_tickets(int sem_id, double quota);
+
+// Must be called with the semaphore meta lock already acquired
+void
+configure_tickets(int sem_id, int tickets, double quota)
+{
+  int state = 0;
+  update_ticket_count_t tc;
+
+  if (quota > 0) {
+    tickets = calculate_quota_tickets(sem_id, quota);
+  }
+
+  /*
+    A manually specified ticket count of 0 is special, meaning "don't set"
+    We need to throw an error if we set it to 0 during initialization.
+    Otherwise, we back out of here completely.
+  */
+  if (get_sem_val(sem_id, SI_SEM_CONFIGURED_TICKETS) == 0 && tickets == 0) {
+    rb_raise(eSyscall, "More than 0 tickets must be specified when initializing semaphore");
+  } else if (tickets == 0) {
+    return;
+  }
+
+  /*
+     If the current configured ticket count is not the same as the requested ticket
+     count, we need to resize the count. We do this by adding the delta of
+     (tickets - current_configured_tickets) to the semaphore value.
+  */
+  if (get_sem_val(sem_id, SI_SEM_CONFIGURED_TICKETS) != tickets) {
+
+    tc.sem_id = sem_id;
+    tc.tickets = tickets;
+    rb_protect((VALUE (*)(VALUE)) update_ticket_count, (VALUE) &tc, &state);
+
+    if (state) {
+      rb_jump_tag(state);
+    }
+  }
+}
+
+static VALUE
 update_ticket_count(update_ticket_count_t *tc)
 {
   short delta;
   struct timespec ts = { 0 };
   ts.tv_sec = INTERNAL_TIMEOUT;
 
-  if (get_max_tickets(tc->sem_id) != tc->tickets) {
-    delta = tc->tickets - get_max_tickets(tc->sem_id);
+  delta = tc->tickets - get_sem_val(tc->sem_id, SI_SEM_CONFIGURED_TICKETS);
 
-    if (perform_semop(tc->sem_id, SI_SEM_TICKETS, delta, 0, &ts) == -1) {
+#ifdef DEBUG
+  print_sem_vals(tc->sem_id);
+#endif
+  if (perform_semop(tc->sem_id, SI_SEM_TICKETS, delta, 0, &ts) == -1) {
+    if (delta < 0 && errno == EAGAIN) {
+      rb_raise(eTimeout, "timeout while trying to update ticket count");
+    } else {
       rb_raise(eInternal, "error setting ticket count, errno: %d (%s)", errno, strerror(errno));
     }
+  }
 
-    if (semctl(tc->sem_id, SI_SEM_CONFIGURED_TICKETS, SETVAL, tc->tickets) == -1) {
-      rb_raise(eInternal, "error updating max ticket count, errno: %d (%s)", errno, strerror(errno));
-    }
+  if (semctl(tc->sem_id, SI_SEM_CONFIGURED_TICKETS, SETVAL, tc->tickets) == -1) {
+    rb_raise(eInternal, "error configuring ticket count, errno: %d (%s)", errno, strerror(errno));
   }
 
   return Qnil;
 }
 
-void
-configure_tickets(int sem_id, int tickets, int should_initialize)
+static int
+calculate_quota_tickets (int sem_id, double quota)
 {
-  unsigned short init_vals[SI_NUM_SEMAPHORES];
-  struct timeval start_time, cur_time;
-  update_ticket_count_t tc;
-  int state;
-
-  if (should_initialize) {
-    init_vals[SI_SEM_TICKETS] = init_vals[SI_SEM_CONFIGURED_TICKETS] = tickets;
-    init_vals[SI_SEM_LOCK] = 1;
-    if (semctl(sem_id, 0, SETALL, init_vals) == -1) {
-      raise_semian_syscall_error("semctl()", errno);
-    }
-  } else if (tickets > 0) {
-    /* it's possible that we haven't actually initialized the
-       semaphore structure yet - wait a bit in that case */
-    if (get_max_tickets(sem_id) == 0) {
-      gettimeofday(&start_time, NULL);
-      while (get_max_tickets(sem_id) == 0) {
-        usleep(10000); /* 10ms */
-        gettimeofday(&cur_time, NULL);
-        if ((cur_time.tv_sec - start_time.tv_sec) > INTERNAL_TIMEOUT) {
-          rb_raise(eInternal, "timeout waiting for semaphore initialization");
-        }
-      }
-    }
-
-    /*
-       If the current max ticket count is not the same as the requested ticket
-       count, we need to resize the count. We do this by adding the delta of
-       (tickets - current_max_tickets) to the semaphore value.
-    */
-    if (get_max_tickets(sem_id) != tickets) {
-      sem_meta_lock(sem_id);
-
-      tc.sem_id = sem_id;
-      tc.tickets = tickets;
-      rb_protect((VALUE (*)(VALUE)) update_ticket_count, (VALUE) &tc, &state);
-
-      sem_meta_unlock(sem_id);
-
-      if (state) {
-        rb_jump_tag(state);
-      }
-    }
-  }
+  int tickets = 0;
+  tickets = (int) ceil(get_sem_val(sem_id, SI_SEM_REGISTERED_WORKERS) * quota);
+  return tickets;
 }

data/ext/semian/tickets.h

@@ -4,14 +4,10 @@ For logic specific to manipulating semian ticket counts
 #ifndef SEMIAN_TICKETS_H
 #define SEMIAN_TICKETS_H
 
-#include <sysv_semaphores.h>
-
-// Update the ticket count for static ticket tracking
-VALUE
-update_ticket_count(update_ticket_count_t *tc);
+#include "sysv_semaphores.h"
 
 // Set initial ticket values upon resource creation
 void
-configure_tickets(int sem_id, int tickets, int should_initialize);
+configure_tickets(int sem_id, int tickets, double quota);
 
 #endif // SEMIAN_TICKETS_H

data/ext/semian/types.h

@@ -4,6 +4,7 @@ For custom type definitions specific to semian
 #ifndef SEMIAN_TYPES_H
 #define SEMIAN_TYPES_H
 
+#include <stdint.h>
 #include <sys/types.h>
 #include <sys/ipc.h>
 #include <sys/sem.h>
@@ -29,17 +30,11 @@ typedef struct {
 typedef struct {
   int sem_id;
   struct timespec timeout;
+  double quota;
   int error;
+  uint64_t key;
+  char *strkey;
   char *name;
 } semian_resource_t;
 
-// FIXME: move this to more appropriate location once the file exists
-typedef enum
-{
-  SI_SEM_TICKETS,            // semaphore for the tickets currently issued
-  SI_SEM_CONFIGURED_TICKETS, // semaphore to track the desired number of tickets available for issue
-  SI_SEM_LOCK,               // metadata lock to act as a mutex, ensuring thread-safety for updating other semaphores
-  SI_NUM_SEMAPHORES          // always leave this as last entry for count to be accurate
-} semaphore_indices;
-
 #endif // SEMIAN_TYPES_H

data/lib/semian.rb

@@ -1,5 +1,7 @@
 require 'forwardable'
 require 'logger'
+require 'weakref'
+require 'thread'
 
 require 'semian/version'
 require 'semian/instrumentable'
@@ -77,7 +79,6 @@ require 'semian/simple_state'
 #    end
 #
 # This is the same as the previous example, but overrides the timeout from the default value of 500 milliseconds to 1 second.
-#
 module Semian
   extend self
   extend Instrumentable
@@ -116,38 +117,58 @@ module Semian
 
   # Registers a resource.
   #
-  # +name+: Name of the resource - this can be either a string or symbol.
+  # +name+: Name of the resource - this can be either a string or symbol. (required)
+  #
+  # +circuit_breaker+: The boolean if you want a circuit breaker acquired for your resource. Default true.
+  #
+  # +bulkhead+: The boolean if you want a bulkhead to be acquired for your resource. Default true.
   #
   # +tickets+: Number of tickets. If this value is 0, the ticket count will not be set,
   # but the resource must have been previously registered otherwise an error will be raised.
+  # Mutually exclusive with the 'quota' argument.
   #
-  # +permissions+: Octal permissions of the resource.
+  # +quota+: Calculate tickets as a ratio of the number of registered workers.
+  # Must be greater than 0, less than or equal to 1. There will always be at least 1 ticket, as it
+  # is calculated as (workers * quota).ceil
+  # Mutually exclusive with the 'ticket' argument.
+  # but the resource must have been previously registered otherwise an error will be raised. (bulkhead)
   #
-  # +timeout+: Default timeout in seconds.
+  # +permissions+: Octal permissions of the resource. Default 0660. (bulkhead)
   #
-  # +error_threshold+: The number of errors that will trigger the circuit opening.
+  # +timeout+: Default timeout in seconds. Default 0. (bulkhead)
+  #
+  # +error_threshold+: The number of errors that will trigger the circuit opening. (circuit breaker required)
   #
   # +error_timeout+: The duration in seconds since the last error after which the error count is reset to 0.
+  # (circuit breaker required)
   #
   # +success_threshold+: The number of consecutive success after which an half-open circuit will be fully closed.
+  # (circuit breaker required)
   #
-  # +exceptions+: An array of exception classes that should be accounted as resource errors.
+  # +exceptions+: An array of exception classes that should be accounted as resource errors. Default [].
+  # (circuit breaker)
   #
   # Returns the registered resource.
-  def register(name, tickets:, permissions: 0660, timeout: 0, error_threshold:, error_timeout:, success_threshold:, exceptions: [])
-    circuit_breaker = CircuitBreaker.new(
-      name,
-      success_threshold: success_threshold,
-      error_threshold: error_threshold,
-      error_timeout: error_timeout,
-      exceptions: Array(exceptions) + [::Semian::BaseError],
-      implementation: ::Semian::Simple,
-    )
-    resource = Resource.new(name, tickets: tickets, permissions: permissions, timeout: timeout)
-    resources[name] = ProtectedResource.new(resource, circuit_breaker)
+  def register(name, **options)
+    circuit_breaker = create_circuit_breaker(name, **options)
+    bulkhead = create_bulkhead(name, **options)
+
+    if circuit_breaker.nil? && bulkhead.nil?
+      raise ArgumentError, 'Both bulkhead and circuitbreaker cannot be disabled.'
+    end
+
+    resources[name] = ProtectedResource.new(name, bulkhead, circuit_breaker)
   end
 
   def retrieve_or_register(name, **args)
+    # If consumer who retrieved / registered by a Semian::Adapter, keep track
+    # of who the consumer was so that we can clear the resource reference if needed.
+    if consumer = args.delete(:consumer)
+      if consumer.class.include?(Semian::Adapter)
+        consumers[name] ||= []
+        consumers[name] << WeakRef.new(consumer)
+      end
+    end
     self[name] || register(name, **args)
   end
 
@@ -162,10 +183,83 @@ module Semian
     end
   end
 
+  # Unregister will not destroy the semian resource, but it will
+  # remove it from the hash of registered resources, and decrease
+  # the number of registered workers.
+  # Semian.destroy removes the underlying resource, but
+  # Semian.unregister will remove all references, while preserving
+  # the underlying semian resource (and sysV semaphore).
+  # Also clears any semian_resources
+  # in use by any semian adapters if the weak reference is still alive.
+  def unregister(name)
+    if resource = resources.delete(name)
+      resource.bulkhead.unregister_worker if resource.bulkhead
+      consumers_for_resource = consumers.delete(name) || []
+      consumers_for_resource.each do |consumer|
+        begin
+          if consumer.weakref_alive?
+            consumer.clear_semian_resource
+          end
+        rescue WeakRef::RefError
+          next
+        end
+      end
+    end
+  end
+
+  # Unregisters all resources
+  def unregister_all_resources
+    resources.keys.each do |resource|
+      unregister(resource)
+    end
+  end
+
   # Retrieves a hash of all registered resources.
   def resources
     @resources ||= {}
   end
+
+  # Retrieves a hash of all registered resource consumers.
+  def consumers
+    @consumers ||= {}
+  end
+
+  def reset!
+    @consumers = {}
+    @resources = {}
+  end
+
+  private
+
+  def create_circuit_breaker(name, **options)
+    circuit_breaker = options.fetch(:circuit_breaker, true)
+    return unless circuit_breaker
+    raise ArgumentError unless required_keys?([:success_threshold, :error_threshold, :error_timeout], options)
+    implementation = options[:thread_safety_disabled] ? ::Semian::Simple : ::Semian::ThreadSafe
+
+    exceptions = options[:exceptions] || []
+    CircuitBreaker.new(
+      name,
+      success_threshold: options[:success_threshold],
+      error_threshold: options[:error_threshold],
+      error_timeout: options[:error_timeout],
+      exceptions: Array(exceptions) + [::Semian::BaseError],
+      implementation: implementation,
+    )
+  end
+
+  def create_bulkhead(name, **options)
+    bulkhead = options.fetch(:bulkhead, true)
+    return unless bulkhead
+
+    permissions = options[:permissions] || 0660
+    timeout = options[:timeout] || 0
+    Resource.new(name, tickets: options[:tickets], quota: options[:quota], permissions: permissions, timeout: timeout)
+  end
+
+  def required_keys?(required = [], **options)
+    required.all? { |key| options.key? key }
+  end
 end
 
 if Semian.semaphores_enabled?

data/lib/semian/adapter.rb

@@ -16,12 +16,17 @@ module Semian
       else
         options = semian_options.dup
         options.delete(:name)
+        options[:consumer] = self
         options[:exceptions] ||= []
         options[:exceptions] += resource_exceptions
         ::Semian.retrieve_or_register(semian_identifier, **options)
       end
     end
 
+    def clear_semian_resource
+      @semian_resource = nil
+    end
+
     private
 
     def acquire_semian_resource(scope:, adapter:, &block)