module Lev::Routine
A “routine” in the Lev
world is a piece of code that is responsible for doing one thing, normally acting on one or more other objects. Routines are particularly useful when the thing that needs to be done involves making changes to multiple other objects. In an OO/MVC world, an operation that involves multiple objects might be implemented by spreading that logic among those objects. However, that leads to classes having more responsibilities than they should (and more knowlege of other classes than they should) as well as making the code hard to follow.
Routines typically don’t have any persistent state that is used over and over again; they are created, used, and forgotten. A routine is a glorified function with a special single-responsibility purpose.
Routines can be nested – there is built-in functionality for calling one routine inside another.
A class becomes a routine by adding:
lev_routine
in its definition.
Other than that, all a routine has to do is implement an “exec” method that takes arbitrary arguments and that adds errors to an internal array-like “errors” object and outputs to a “outputs” hash.
A routine returns an “Result” object, which is just a simple wrapper of the outputs and errors objects.
A routine will automatically get both class- and instance-level “call” methods that take the same arguments as the “exec” method. The class-level call method simply instantiates a new instance of the routine and calls the instance-level call method (side note here is that this means that routines aren’t typically instantiated with state).
A routine is automatically run within a transaction. The isolation level of the routine can be set by passing a :transaction option to the lev_routine call (or to the lev_handler call, if appropriate). The value must be one of
:no_transaction :read_uncommitted :read_committed :repeatable_read :serializable
e.g.
class MyRoutine lev_routine transaction: :no_transaction
As mentioned above, routines can call other routines. While this is of course possible just by calling the other routine’s call method directly, it is strongly recommended that one routine call another routine using the provided “run” method. This method takes the name of the routine class and the arguments/block it expects in its call/exec methods. By using the run method, the called routine will be hooked into the common error and transaction mechanisms.
When one routine is called within another using the run method, there is only one transaction used (barring any explicitly made in the code) and its isolation level is sufficiently strict for all routines involved.
It is highly recommend, though not required, to call the “uses_routine” method to let the routine know which subroutines will be called within it. This will let a routine set its isolation level appropriately, and will enforce that only one transaction be used and that it be rolled back appropriately if any errors occur.
Once a routine has been registered with the “uses_routine” call, it can be run by passing run the routine’s Class or a symbol identifying the routine. This symbol can be set with the :as option. If not set, the symbol will be automatically set by converting the routine class’ full name to a symbol. e.g:
uses_routine CreateUser as: :cu
and then you can say either:
run(:cu, ...)
or
run(:create_user, ...)
uses_routine also provides a way to specify how errors relate to routine inputs. Take the following example. A user calls Routine1 which calls Routine2.
User --> Routine1.call(foo: "abcd4") --> Routine2.call(bar: "abcd4")
An error occurs in Routine2, and Routine2 notes that the error is related to its “bar” input. If that error and its metadata bubble up to the User, the User won’t have any idea what “bar” relates to – the User only knows about the interface to Routine1 and the “foo” parameter it gave it.
Routine1 knows that it will call Routine2 and knows what its interface is. It can then specify how to map terminology from Routine2 into Routine1’s context. E.g., in the following class:
class Routine1 lev_routine uses_routine Routine2, translations: { inputs: { map: {bar: :foo} } } def exec(options) run(Routine2, bar: options[:foo]) end end
Routine1 notes that any errors coming back from the call to Routine2 related to :bar should be transfered into Routine1’s errors object as being related to :foo. In this way, the caller of Routine1 will see errors related to the arguments he understands.
Translations can also be supplied for “outputs” in addition to “inputs”. Output translations control how a called routine’s Result
outputs are transfered to the calling routine’s outputs. Note if multiple outputs are transferred into the same named output, an array of those outputs will be store. The contents of the “inputs” and “outputs” hashes can be of the following form:
1) Scoped. Appends the provided scoping symbol (or symbol array) to
the input symbol. {scope: SCOPING_SYMBOL_OR_SYMBOL_ARRAY} e.g. with {scope: :register} and a call to a routine that has an input named :first_name, an error in that called routine related to its :first_name input will be translated so that the offending input is [:register, :first_name].
2) Verbatim. Uses the same term in the caller as the callee.
{type: :verbatim}
3) Mapped. Give an explicit, custom mapping:
{map: {called_input1: caller_input1, called_input2: :caller_input2}}
4) Scoped and mapped. Give an explicit mapping, and also scope the
translated terms. Just use scope: and map: from above in the same hash.
Via the uses_routine call, you can also ignore specified errors that occur in the called routine. e.g.:
uses_routine DestroyUser, ignored_errors: [:cannot_destroy_non_temp_user]
ignores errors with the provided code. The ignore_errors key must point to an array of code symbols or procs. If a proc is given, the proc will be called with the error that the routine is trying to add. If the proc returns true, the error will be ignored.
Any option passed to uses_routine can also be passed directly to the run method. To achieve this, pass an array as the first argument to “run”. The array should have the routine class or symbol as the first argument, and the hash of options as the second argument. Options passed in this manner override any options provided in uses_routine (though those options are still used if not replaced in the run call).
Two methods are provided for adding errors: “fatal_error” and “nonfatal_error”. Both take a hash of args used to create an Error
and the former stops routine execution. In its current implementation, “nonfatal_error” may still cause a routine higher up in the execution hierarchy to halt running.
Routine
class have access to a few other methods:
1) a "runner" accessor which points to the routine which called it. If runner is nil that means that no other routine called it (some other code did) 2) a "topmost_runner" which points to the highest routine in the calling hierarchy (that routine whose 'runner' is nil)
References:
http://ducktypo.blogspot.com/2010/08/why-inheritance-sucks.html
Attributes
Public Class Methods
# File lib/lev/routine.rb, line 195 def self.included(base) base.extend(ClassMethods) base.class_attribute :create_status_proc, :find_status_proc base.create_status_proc = ->(*) { NullStatus.new } base.find_status_proc = ->(*) { NullStatus.new } end
Note that the parent may neglect to call super, leading to this method never being called. Do not perform any initialization here that cannot be safely skipped
# File lib/lev/routine.rb, line 448 def initialize(status = nil) # If someone cares about the status, they'll pass it in; otherwise all # status updates go into the bit bucket. @status = status end
Public Instance Methods
# File lib/lev/routine.rb, line 441 def add_after_transaction_block(block) raise IllegalOperation if topmost_runner != self @after_transaction_blocks.push(block) end
# File lib/lev/routine.rb, line 282 def call(*args, **kwargs, &block) @after_transaction_blocks = [] status.started! begin in_transaction do reset_result! if transaction_run_by?(self) catch :fatal_errors_encountered do if self.class.delegates_to run(self.class.delegates_to, *args, **kwargs, &block) else exec(*args, **kwargs, &block) end end end @after_transaction_blocks.each do |block| block.call end rescue Exception => e # Let exceptions escape but make sure to note the error in the status if not already done if !e.is_a?(Lev::FatalError) error = Error.new(code: :exception, message: e.message, data: e.backtrace&.first) status.add_error(error) status.failed! end raise e end status.succeeded! if !errors? result end
Convenience accessor for errors object
# File lib/lev/routine.rb, line 411 def errors result.errors end
Convenience test for presence of errors
# File lib/lev/routine.rb, line 416 def errors? result.errors.any? end
# File lib/lev/routine.rb, line 420 def fatal_error(args={}) errors.add(true, args) end
# File lib/lev/routine.rb, line 424 def nonfatal_error(args={}) errors.add(false, args) end
# File lib/lev/routine.rb, line 327 def run(other_routine, *args, **kwargs, &block) options = {} if other_routine.is_a? Array if other_routine.size != 2 raise Lev.configuration.illegal_argument_error, "when first arg to run is an array, it must have two arguments" end other_routine = other_routine[0] options = other_routine[1] end symbol = case other_routine when Symbol other_routine when Class self.class.class_to_symbol(other_routine) else self.class.class_to_symbol(other_routine.class) end nested_routine = self.class.nested_routines[symbol] || {} if nested_routine.empty? && other_routine == symbol raise Lev.configuration.illegal_argument_error, "Routine symbol #{other_routine} does not point to a registered routine" end # # Get an instance of the routine and make sure it is a routine # other_routine = nested_routine[:routine_class] || other_routine other_routine = other_routine.new if other_routine.is_a? Class if !(other_routine.includes_module? Lev::Routine) raise Lev.configuration.illegal_argument_error, "Can only run another nested routine" end # # Merge passed-in options with those set in uses_routine, the former taking # priority. # nested_routine_options = nested_routine[:options] || {} options = Lev::Utilities.deep_merge(nested_routine_options, options) # # Setup the input/output mappers # options[:translations] ||= {} input_mapper = new_term_mapper(options[:translations][:inputs]) || new_term_mapper({ scope: symbol }) output_mapper = new_term_mapper(options[:translations][:outputs]) # # Set up the ignored errors in the routine instance # (options[:ignored_errors] || []).each do |ignored_error| other_routine.errors.ignore(ignored_error) end # # Attach the subroutine to self, call it, transfer outputs and errors # other_routine.runner = self run_result = other_routine.call(*args, **kwargs, &block) run_result.outputs.transfer_to(outputs) do |name| output_mapper.map(name) end unless output_mapper.nil? options[:errors_are_fatal] = true if !options.has_key?(:errors_are_fatal) transfer_errors_from(run_result.errors, input_mapper, options[:errors_are_fatal]) run_result end
Returns true iff the given instance is responsible for running itself in a transaction
# File lib/lev/routine.rb, line 323 def transaction_run_by?(who) who == topmost_runner && who.class.transaction_isolation != TransactionIsolation.no_transaction end
Utility method to transfer errors from a source to this routine. The provided input_mapper maps the language of the errors in the source to the language of this routine. If fail_if_errors is true, this routine will throw an error condition that causes execution of this routine to stop after having transfered all of the errors.
# File lib/lev/routine.rb, line 433 def transfer_errors_from(source, input_mapper, fail_if_errors=false) if input_mapper.is_a? Hash input_mapper = new_term_mapper(input_mapper) end ErrorTransferer.transfer(source, self, input_mapper, fail_if_errors) end
Protected Instance Methods
# File lib/lev/routine.rb, line 480 def after_transaction(&block) topmost_runner.add_after_transaction_block(block) end
# File lib/lev/routine.rb, line 495 def in_transaction(options={}) if transaction_run_by?(self) isolation_symbol = self.class.transaction_isolation.symbol if (ActiveRecord::VERSION::MAJOR >= 8 || (ActiveRecord::VERSION::MAJOR == 7 && ActiveRecord::VERSION::MINOR >= 1)) && ActiveRecord::Base.connection.transaction_open? # Don't even try to set transaction isolation if the transaction is already open ActiveRecord::Base.transaction do yield raise ActiveRecord::Rollback if errors? end elsif ActiveRecord::VERSION::MAJOR >= 4 begin ActiveRecord::Base.transaction(isolation: isolation_symbol) do yield raise ActiveRecord::Rollback if errors? end rescue ActiveRecord::TransactionIsolationError # Silently ignore isolation errors ActiveRecord::Base.transaction do yield raise ActiveRecord::Rollback if errors? end end else ActiveRecord::Base.isolation_level(isolation_symbol) do ActiveRecord::Base.transaction do yield raise ActiveRecord::Rollback if errors? end end end else yield end end
# File lib/lev/routine.rb, line 532 def new_term_mapper(options) return nil if options.nil? if options[:type] case options[:type] when :verbatim return TermMapper.verbatim else raise Lev.configuration.illegal_argument_error, "unknown :type value: #{options[:type]}" end end if options[:scope] || options[:map] return TermMapper.scope_and_map(options[:scope], options[:map]) end nil end
# File lib/lev/routine.rb, line 472 def outputs result.outputs end
# File lib/lev/routine.rb, line 468 def reset_result! @result = nil end
# File lib/lev/routine.rb, line 462 def result @result ||= Result.new( Outputs.new, Errors.new(status, topmost_runner.class.raise_fatal_errors?) ) end
# File lib/lev/routine.rb, line 484 def runner=(runner) @runner = runner if topmost_runner.class.transaction_isolation.weaker_than(self.class.transaction_isolation) raise IsolationMismatch, "The routine being run has a stronger isolation requirement than " + "the isolation being used by the routine(s) running it; call the " + "'uses' method in the running routine's initializer" end end
# File lib/lev/routine.rb, line 458 def status @status ||= Lev::NullStatus.new end
# File lib/lev/routine.rb, line 476 def topmost_runner runner.nil? ? self : runner.topmost_runner end