pantheios-ruby 0.18.1 → 0.21.0

data/examples/simple_logging.rb

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), *([ '..' ] * 1), 'lib')
+
+# requires (0)
+
+require 'pantheios/globals'
+
+# globals
+
+Pantheios::Globals.MAIN_THREAD_NAME = [ Thread.current, 'main' ]
+Pantheios::Globals.PROCESS_NAME = :script_stem
+
+# requires (1)
+
+require 'pantheios'
+
+# includes
+
+include ::Pantheios
+
+# constants
+
+LEVELS = %i{ violation alert critical failure warning notice informational debug0 debug1 debug2 debug3 debug4 }
+
+# main
+
+LEVELS.each do |level|
+
+	log(level, "logging level #{level}")
+end
+
+# ############################## end of file ############################# #
+
+

data/lib/pantheios/application_layer/stock_severity_levels.rb

@@ -7,12 +7,13 @@
 #               namespace module
 #
 # Created:      2nd April 2011
-# Updated:      6th January 2018
+# Updated:      3rd June 2020
 #
 # Home:         http://github.com/synesissoftware/Pantheios-Ruby
 #
 # Author:       Matthew Wilson
 #
+# Copyright (c) 2019-2020, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2011-2018, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -59,20 +60,21 @@ module StockSeverityLevels
 
 		STOCK_SEVERITY_LEVELS_ = {
 
-			:violation => [ 1, 'Violation', [ :emergency ] ],
-			:alert => [ 2, 'Alert' ],
-			:critical => [ 3, 'Critical' ],
-			:failure => [ 4, 'Failure' ],
-			:warning => [ 5, 'Warning', [ :warn ] ],
-			:notice => [ 6, 'Notice' ],
-			:informational => [ 7, 'Informational', [ :info ] ],
-			:debug0 => [ 8, 'Debug-0' ],
-			:debug1 => [ 9, 'Debug-1' ],
-			:debug2 => [ 10, 'Debug-2' ],
-			:debug3 => [ 11, 'Debug-3' ],
-			:debug4 => [ 12, 'Debug-4' ],
-			:trace => [ 13, 'Trace' ],
-			:benchmark => [ 14, 'Benchmark' ],
+			:violation => [ 1, 'Violation', :relative, [ :emergency ] ],
+			:alert => [ 2, 'Alert', :relative ],
+			:critical => [ 3, 'Critical', :relative ],
+			:failure => [ 4, 'Failure', :relative, [ :fail ] ],
+			:warning => [ 5, 'Warning', :relative, [ :warn ] ],
+			:notice => [ 6, 'Notice', :relative ],
+			:informational => [ 7, 'Informational', :relative, [ :info ] ],
+			:debug0 => [ 8, 'Debug-0', :relative ],
+			:debug1 => [ 9, 'Debug-1', :relative ],
+			:debug2 => [ 10, 'Debug-2', :relative ],
+			:debug3 => [ 11, 'Debug-3', :relative ],
+			:debug4 => [ 12, 'Debug-4', :relative ],
+			:debug5 => [ 13, 'Debug-5', :relative ],
+			:trace => [ 15, 'Trace', :relative ],
+			:benchmark => [ 16, 'Benchmark', :separate ],
 		}
 
 		def self.create_level_keys m
@@ -81,7 +83,7 @@ module StockSeverityLevels
 
 			m.each do |k, ar|
 
-				(ar[2] || []).each do |al|
+				(ar[3] || []).each do |al|
 
 					r << al
 				end
@@ -99,7 +101,7 @@ module StockSeverityLevels
 				warn 'invalid start-up' unless ::Symbol === s
 				warn 'invalid start-up' unless ::Array === ar
 
-				([s] + (ar[2] || [])).each do |al|
+				([s] + (ar[3] || [])).each do |al|
 
 					r[al] = ar[0]
 				end
@@ -107,6 +109,7 @@ module StockSeverityLevels
 
 			r
 		end
+
 		def self.create_level_string_map m
 
 			r = {}
@@ -116,7 +119,7 @@ module StockSeverityLevels
 				warn 'invalid start-up' unless ::Symbol === s
 				warn 'invalid start-up' unless ::Array === ar
 
-				([s] + (ar[2] || [])).each do |al|
+				([s] + (ar[3] || [])).each do |al|
 
 					r[al] = ar[1]
 				end
@@ -124,20 +127,74 @@ module StockSeverityLevels
 
 			r
 		end
+
+		def self.create_level_aliases m
+
+			r = {}
+
+			m.each do |s, ar|
+
+				warn 'invalid start-up' unless ::Symbol === s
+				warn 'invalid start-up' unless ::Array === ar
+
+				([s] + (ar[3] || [])).each do |al|
+
+					r[al] = s
+				end
+			end
+
+			r
+		end
+
+		def self.create_level_relative_map m
+
+			r = {}
+
+			m.each do |s, ar|
+
+				warn 'invalid start-up' unless ::Symbol === s
+				warn 'invalid start-up' unless ::Array === ar
+
+				relativity = ar[2]
+
+				case relativity
+				when :relative
+
+					([s] + (ar[3] || [])).each do |al|
+
+						r[al] = relativity
+					end
+				else
+
+					;
+				end
+			end
+
+			r
+		end
 	end
 	public
 
-	# Ordered list of stock severity levels, without any aliases
+	# Ordered list of stock severity level symbols, without any aliases
 	STOCK_SEVERITY_LEVELS_PRIME = Internal_::STOCK_SEVERITY_LEVELS_.keys
 
-	# Ordered list of stock severity levels, some of which may be aliases
+	# Unordered list of stock severity levels, some of which may be aliases
 	STOCK_SEVERITY_LEVELS = Internal_.create_level_keys Internal_::STOCK_SEVERITY_LEVELS_
 
-	# Mapping of severity levels (and level aliases) to integral
+	# Mapping of severity level aliases - with may be symbols and strings -
+	# to the prime stock severity level symbols
+	STOCK_SEVERITY_LEVEL_ALIASES = Internal_.create_level_aliases Internal_::STOCK_SEVERITY_LEVELS_
+
+	# Mapping of severity level aliases - with may be symbols and strings -
+	# containing only those levels that are relative, i.e. may participate
+	# meaningfully in a threshold-based filtering
+	STOCK_SEVERITY_LEVELS_RELATIVE = Internal_.create_level_relative_map Internal_::STOCK_SEVERITY_LEVELS_
+
+	# Mapping of severity level (and level alias) symbols to integral
 	# equivalent
 	STOCK_SEVERITY_LEVEL_VALUES = Internal_.create_level_value_map Internal_::STOCK_SEVERITY_LEVELS_
 
-	# Mapping of severity levels (and level aliases) to string
+	# Mapping of severity level (and level alias) symbols to string
 	STOCK_SEVERITY_LEVEL_STRINGS = Internal_.create_level_string_map Internal_::STOCK_SEVERITY_LEVELS_
 
 end # module StockSeverityLevels

data/lib/pantheios/core.rb

@@ -5,7 +5,7 @@
 # Purpose:      The Pantheios.Ruby core (::Pantheios::Core)
 #
 # Created:      2nd April 2011
-# Updated:      5th February 2018
+# Updated:      5th September 2018
 #
 # Home:         http://github.com/synesissoftware/Pantheios-Ruby
 #
@@ -506,7 +506,7 @@ module Core
 
 		if block_given?
 
-			br = get_block_value_ &block
+			br = get_block_value_(&block)
 
 			if ApplicationLayer::ParamNameList === br
 
@@ -527,20 +527,21 @@ module Core
 			end
 		end
 
+		fl	=	nil
+		rx	=	nil
+		fn	=	caller(call_depth + 1, 1)[0]
+
 		case param_list
 		when nil
 			;
 		when ApplicationLayer::ParamNameList
-			;
+
+			warn "#{fn}: param_list must contain only strings or symbols" unless param_list.all? { |p| p.kind_of?(::String) || p.kind_of?(::Symbol) }
 		else
 
-			warn "param_list (#{param_list.class}) must be nil or an instance of #{ApplicationLayer::ParamNameList}" unless param_list
+			warn "#{fn}: param_list (#{param_list.class}) must be nil or an instance of #{ApplicationLayer::ParamNameList}" unless param_list
 		end
 
-		fl	=	nil
-		rx	=	nil
-		fn	=	caller(call_depth + 1, 1)[0]
-
 		if ::Class === prefix_provider
 
 			rx	=	"#{prefix_provider}::"

data/lib/pantheios/front_ends/threshold_front_end.rb

@@ -0,0 +1,135 @@
+
+# ######################################################################## #
+# File:         lib/pantheios/front_ends/threshold_front_end.rb
+#
+# Purpose:      Definition of the ::Pantheios::FrontEnds::ThresholdFrontEnd
+#               class
+#
+# Created:      3rd June 2020
+# Updated:      3rd June 2020
+#
+# Home:         http://github.com/synesissoftware/Pantheios-Ruby
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2020, Matthew Wilson and Synesis Information Systems
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+#   notice, this list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+#
+# * Neither the names of the copyright holder nor the names of its
+#   contributors may be used to endorse or promote products derived from
+#   this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# ######################################################################## #
+
+
+=begin
+=end
+
+require 'pantheios/application_layer/stock_severity_levels'
+
+module Pantheios
+module FrontEnds
+
+# A class that fulfils the Pantheios *FrontEnd* protocol that implements
+# +severity_logged?+ based on a threshold specified to the initialiser
+#
+# NOTE: The *FrontEnd* protocol is implemented by a class that provides
+# the instance method +severity_logged?(severity : Object)+
+class ThresholdFrontEnd
+
+	include ::Pantheios::ApplicationLayer
+
+	# Initialises the instance
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +threshold_severity+ [ ::Symbol ] The threshold severity
+	#
+	# * *Options:*
+	#   - +value_lookup_map+ [ ::Hash ] A map that is used to lookup
+	#     +severity+ values (that are not +::Integer+) in
+	#     +severity_logged?+. May be +nil+, in which case
+	#     +::Pantheios::ApplicationLayer::StockSeverityLevels::STOCK_SEVERITY_LEVEL_VALUES+
+	#     is used
+	def initialize(threshold_severity, **options)
+
+		m = options[:value_lookup_map]
+
+		raise TypeError, "value given for :value_lookup_map must be a #{::Hash}" if m && !m.respond_to?(:to_hash)
+
+		if m
+
+			@value_lookup_map = m
+			@relativity_lookup_map = ::Hash.new(:relative)
+		else
+
+			@value_lookup_map = StockSeverityLevels::STOCK_SEVERITY_LEVEL_VALUES
+			@relativity_lookup_map = StockSeverityLevels::STOCK_SEVERITY_LEVELS_RELATIVE
+		end
+
+		self.threshold = threshold_severity
+	end
+
+	def severity_logged? severity
+
+		case severity
+		when ::Integer
+
+			v = severity
+		else
+
+			v = @value_lookup_map[severity] or warn "unknown severity level '#{severity}' (#{severity.class})"
+		end
+
+		return true if v.nil?
+
+		v <= @threshold_v
+	end
+
+	# assigns the threshold
+	#
+	# * *Parameters:*
+	#   - +threshold_severity+ [ ::Symbol ] The threshold severity
+	def threshold=(threshold_severity)
+
+		raise TypeError, "threshold_severity must be a #{::Symbol}" unless ::Symbol === threshold_severity
+
+		@threshold_v = @value_lookup_map[threshold_severity] if @relativity_lookup_map[threshold_severity] or raise ArgumentError, "unknown threshold severity level '#{threshold_severity}' (#{threshold_severity.class})"
+		@threshold = threshold_severity
+
+		nil
+	end
+	attr_reader :threshold
+
+end # class ThresholdFrontEnd
+
+end # module FrontEnds
+end # module Pantheios
+
+# ############################## end of file ############################# #
+
+

data/lib/pantheios/globals.rb

@@ -5,12 +5,13 @@
 # Purpose:      The Pantheios.Ruby "globals" (::Pantheios::Globals)
 #
 # Created:      24th December 2017
-# Updated:      4th February 2018
+# Updated:      3rd June 2020
 #
 # Home:         http://github.com/synesissoftware/Pantheios-Ruby
 #
 # Author:       Matthew Wilson
 #
+# Copyright (c) 2019-2020, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2017-2018, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -57,6 +58,18 @@ module Pantheios
 #
 # === Variables
 #
+# * *HAS_CASCADED_INCLUDES* [boolean] Determines whether including
+#   +::Pantheios+ also includes all relevant parts of subordinate
+#   namespaces. See the documentation for the +::Pantheios+ namespace for
+#   further details
+#
+# * *INITIAL_SERVICE_CLASSES* [ svc-class, [ svc-class ] ] Specifies
+#   the service class(es) that will be used to create the initial service
+#   instance. Ignored if INITIAL_SERVICE_INSTANCES specifies an instance
+#
+# * *INITIAL_SERVICE_INSTANCES* [ svc-instance, [ svc-instance ] ] Specifies
+#   the initial service instance
+#
 # * *MAIN_THREAD_NAME* A string specifying the main thread name, or an array
 #   containing a thread instance and a string specifying the thread and its
 #   name
@@ -65,11 +78,6 @@ module Pantheios
 #   form is used then the first initialising thread of Pantheios.Ruby will
 #   be the named thread
 #
-# * *HAS_CASCADED_INCLUDES* [boolean] Determines whether including
-#   +::Pantheios+ also includes all relevant parts of subordinate
-#   namespaces. See the documentation for the +::Pantheios+ namespace for
-#   further details
-#
 # * *PROCESS_NAME* A string specifying the process name, or one of the
 #   recognised symbols - :script, :script_basename, :script_dirname,
 #   :script_realpath, :script_stem - that directs inference of the process

data/lib/pantheios/services.rb

@@ -0,0 +1,3 @@
+
+Dir[File.join(File.dirname(__FILE__), 'services', '*log_service.rb')].each { |f| require f }
+

data/lib/pantheios/services/multiplexing_log_service.rb

@@ -0,0 +1,239 @@
+
+# ######################################################################## #
+# File:         lib/pantheios/services/multiplexing_log_service.rb
+#
+# Purpose:      Definition of the
+#               ::Pantheios::Services::MultiplexingLogService class
+#
+# Created:      14th June 2015
+# Updated:      8th February 2018
+#
+# Home:         http://github.com/synesissoftware/Pantheios-Ruby
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2015-2018, Matthew Wilson and Synesis Software
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+#   notice, this list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+#
+# * Neither the names of the copyright holder nor the names of its
+#   contributors may be used to endorse or promote products derived from
+#   this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# ######################################################################## #
+
+
+=begin
+=end
+
+module Pantheios
+module Services
+
+# A class that fulfils the Pantheios *LogService* protocol by multiplexing
+# its responsibilities to a number of (concrete) log service instances
+#
+# NOTE: The *LogService* protocol is implemented by a class that provides
+# the instance methods +severity_logged?(severity : Object) : boolean+ and
+# +log(severity : Object, t : Time, prefix : String, msg : String)+
+class MultiplexingLogService
+
+	module MultiplexingLogService_Internals_
+
+		class ServiceManagementInfo
+
+			def initialize svc
+
+				@service	=	svc
+			end
+
+			attr_reader	:service
+		end
+	end
+
+	# Initializes the instance with an array of log services, according to
+	# the given options
+	#
+	# ===Signature
+	#
+	# * *Parameters:*
+	#   - +services+:: [ ::Array ] An array of instances that observe the
+	#     Log Service protocol
+	#   - +options+:: [ ::Hash] options
+	#
+	# * *Options:*
+	#   - +:level_cache_mode+:: [ ::Symbol ] Specifies the mode of severity
+	#     level caching, and must be one of the following values:
+	#     * +:none+:: no severity level caching is performed. This is the
+	#       default because it is completely thread-safe, but it is the
+	#       slowest mode, and users are advised to specify another mode
+	#       suitable to their use
+	#     * +:thread_fixed+:: remembers the response of each multiplexed log
+	#       service to each severity level on a thread-specific basis
+	#     * +:process_fixed+:: remembers the response of each multiplexed
+	#       log service to each severity level and then remembers that for
+	#       the duration of the lifetime of the instance
+	#   - +:unsync_process_lcm+:: [ boolean ] If truey, causes
+	#     +:process_fixed+ +:level_cache_mode+ to NOT be synchronised; the
+	#     default is for it to be synchronised using an internal +Mutex+
+	#     instance
+	def initialize services, **options
+
+		@tss_sym	=	self.to_s.to_sym
+		@services	=	services.map { |svc| MultiplexingLogService_Internals_::ServiceManagementInfo.new svc }
+		@options	=	options.dup
+		@mode		=	options[:level_cache_mode]
+		@unsync_pf	=	options[:unsync_process_lcm]
+
+		@process_m	=	{}
+		@mx			=	Mutex.new unless @unsync_pf
+	end
+
+	private
+
+	# { svc => { sev => flag } }
+	def get_tss_svc_sev_map_
+
+		sym	=	@tss_sym
+		tc	=	Thread.current
+		m	=	tc.thread_variable_get sym
+
+		unless m
+
+			tc.thread_variable_set sym, (m = {})
+		end
+
+		m
+	end
+
+	def svc_sev_logged_tf_ m, svc, severity
+
+		m[svc.object_id]	||=	{}
+
+		unless m[svc.object_id].has_key? severity
+
+			r = svc.severity_logged? severity
+
+			m[svc.object_id][severity] = r
+		else
+
+			r = m[svc.object_id][severity]
+		end
+
+		r
+	end
+
+	def svc_sev_logged_pf_ m, svc, severity
+
+		m[svc.object_id]	||=	{}
+
+		unless m[svc.object_id].has_key? severity
+
+			r = svc.severity_logged? severity
+
+			m[svc.object_id][severity] = r
+		else
+
+			r = m[svc.object_id][severity]
+		end
+
+		r
+	end
+
+	def sev_logged_pf_ m, severity
+
+		@services.any? { |smi| svc_sev_logged_pf_ m, smi.service, severity }
+	end
+	public
+
+	# Indicates whether the given severity is to be logged by any of the
+	# multiplexed log services
+	def severity_logged? severity
+
+		case @mode
+		when :process_fixed
+
+			if @unsync_pf
+
+				sev_logged_pf_ @process_m, severity
+			else
+
+				@mx.synchronize { sev_logged_pf_ @process_m, severity }
+			end
+		when :thread_fixed
+
+			m	=	get_tss_svc_sev_map_
+
+			@services.any? do |smi|
+
+				svc	=	smi.service
+
+				svc_sev_logged_tf_ m, svc, severity
+			end
+		else # :none
+
+			@services.any? { |smi| smi.service.severity_logged? severity }
+		end
+	end
+
+	def log sev, t, pref, msg
+
+		tss_m	=	:thread_fixed == @mode ? get_tss_svc_sev_map_ : nil
+
+		@services.each do |smi|
+
+			svc	=	smi.service
+
+			case @mode
+			when :process_fixed
+
+				if @unsync_pf
+
+					isl	=	svc_sev_logged_pf_ @process_m, svc, sev
+				else
+
+					isl	=	@mx.synchronize { svc_sev_logged_pf_ @process_m, svc, sev }
+				end
+			when :thread_fixed
+
+				m	=	tss_m
+
+				isl	=	svc_sev_logged_tf_ m, svc, sev
+			else # :none
+
+				isl	=	svc.severity_logged? sev
+			end
+
+
+			svc.log sev, t, pref, msg if isl
+		end
+	end
+end
+
+end # module Services
+end # module Pantheios
+
+# ############################## end of file ############################# #
+
+