Module: Lev::Routine

Defined in:
lib/lev/routine.rb

Overview

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

Defined Under Namespace

Modules: ClassMethods Classes: Result

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#runner ⇒ Object

Returns the value of attribute runner.



233
234
235
 
# File 'lib/lev/routine.rb', line 233

def runner
  @runner
end

Class Method Details

.included(base) ⇒ Object 



194
195
196
 
# File 'lib/lev/routine.rb', line 194

def self.included(base)
  base.extend(ClassMethods)
end

Instance Method Details

#call(*args, &block) ⇒ Object 



235
236
237
238
239
240
241
242
243
 
# File 'lib/lev/routine.rb', line 235

def call(*args, &block)
  in_transaction do
    catch :fatal_errors_encountered do
      exec(*args, &block)
    end
  end

  result
end

#errors ⇒ Object

Convenience accessor for errors object



335
336
337
 
# File 'lib/lev/routine.rb', line 335

def errors
  result.errors
end

#errors? ⇒ Boolean

Convenience test for presence of errors

Returns:

  • (Boolean) 


340
341
342
 
# File 'lib/lev/routine.rb', line 340

def errors?
  result.errors.any?
end

#fatal_error(args = {}) ⇒ Object 



344
345
346
 
# File 'lib/lev/routine.rb', line 344

def fatal_error(args={})
  errors.add(true, args)
end

#nonfatal_error(args = {}) ⇒ Object 



348
349
350
 
# File 'lib/lev/routine.rb', line 348

def nonfatal_error(args={})
  errors.add(false, args)
end

#run(other_routine, *args, &block) ⇒ Object

Raises:

  • (IllegalArgument) 


251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
 
# File 'lib/lev/routine.rb', line 251

def run(other_routine, *args, &block)
  options = {}

  if other_routine.is_a? Array
    if other_routine.size != 2
      raise IllegalArgument, "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 IllegalArgument, 
          "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

  raise IllegalArgument, "Can only run another nested routine" \
    if !(other_routine.includes_module? Lev::Routine)

  #
  # 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]) || 
                  new_term_mapper({ scope: symbol })

  #
  # 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 errors and results
  #

  other_routine.runner = self
  run_result = other_routine.call(*args, &block)

  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.outputs.transfer_to(outputs) do |name|
    output_mapper.map(name)
  end

  run_result
end

#transaction_run_by?(who) ⇒ Boolean

Returns true iff the given instance is responsible for running itself in a transaction

Returns:

  • (Boolean) 


247
248
249
 
# File 'lib/lev/routine.rb', line 247

def transaction_run_by?(who)
  who == topmost_runner && who.class.transaction_isolation != TransactionIsolation.no_transaction
end

#transfer_errors_from(source, input_mapper, fail_if_errors = false) ⇒ Object

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.



357
358
359
360
361
362
363
 
# File 'lib/lev/routine.rb', line 357

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