SmartCore::Engine · ·

Generic SmartCore functionality.

Installation

gem 'smart_engine'

bundle install
# --- or ---
gem install smart_engine

require 'smart_core'

Technologies

Global set of error types
Simple reentrant lock
Read/Write Lock
Cache Storage
Atomic thread-safe value container
Any Object Frozener (classic c-level frozen?/freeze)
Basic Object Refinements (SmartCore::Ext::BasicObjectAsObject)
Inline rescue pipe

Global set of error types

SmartCore::Error (inherited from ::StandardError);
SmartCore::ArgumentError (inherited from ::ArgumentError);
SmartCore::FrozenError (inherited from ::FrozenError);
SmartCore::NameError (inherited from ::NameError);
SmartCore::TypeError (inherited from ::TypeError);

Simple reentrant lock

lock = SmartCore::Engine::Lock.new
lock.synchronize { your_code }

Read/Write Lock

non-controlable reader count;
readers does not lock each other;
readers waits for writer;
writer waits for readers;

lock = SmartCore::Engine::ReadWriteLock.new

lock.read_sync { ...some-read-op... } # waits for writer
lock.read_sync { ...some-read-op... } # waits for writer
lock.write_sync { ... some-write-op... } # waits for all readers and current writer

# is write_sync lock is owned by current thread?
lock.write_owned? # true or false

Cache Storage

you can use any object as a cache key;
you can store any object as a cache value;
you can cache nil object too;
cache read has fetch semantics:
- signature: #read(key, &fallback);
- in the event of cache miss the &fallback black will be invoked;
- the return value of the fallback block will be written to the cache, and that return value will be returned;
cache write:
- signature: #write(key, value);
- you can use any object as a cache key;
- you can store any object as a value;
- you can write nil object too;
cache clear:
- signature: #clear;

cache = SmartCore::Engine::Cache.new

# write and read
cache.write(:amount, 123.456) # => 123.456
cache.read(:amount) # => 123.456

# read non-existing with a fallback
cache.read('name') # => nil
cache.read('name') { 'D@iVeR' } # => 'D@iVeR'
cache.read('name') # => 'D@iVeR'

# store nil object
cache.write(:nil_value, nil) # => nil
cache.read(:nil_value) # => nil
cache.read(:nil_value) { 'rewritten' } # => nil
cache.read(:nil_value) # => nil

# clear cache
cache.clear # => nil

# aliases:

# write:
cache[:key1] = 'test'

# read:
cache[:key1] # => 'test'

# read with fallback:
cache[:key2] { 'test2' } # => 'test2'
cache[:key2] # => 'test2'

Atomic thread-safe value container

atom = SmartCore::Engine::Atom.new # initial value - nil
atom.value # => nil
# --- or ---
atom = SmartCore::Engine::Atom.new(7) # initial value - 7
atom.value # => 7

# set new value (thread-safely)
atom.swap { |original_value| original_value * 2 }
atom.value # => 14

Any Object Frozener

works with any type of ruby objects (event with BasicObject);
uses classic Ruby C-level frozen?/freeze functionality;

# as a singleton

object = BasicObject.new
SmartCore::Engine::Frozener.frozen?(object) # => false

SmartCore::Engine::Frozener.freeze(object)
SmartCore::Engine::Frozener.frozen?(object) # => true

# as a mixin

class EmptyObject < BasicObject
  include SmartCore::Engine::Frozener::Mixin
end

object = EmptyObject.new

object.frozen? # => false
object.freeze
object.frozen? # => true

Basic Object Refinements

Ruby's BasicObject class does not have some fundamental (extremely important for instrumenting) methods:

is_a? / kind_of?
instance_of?
freeze / frozen?
hash
nil?
inspect

SmartCore::Ext::BasicObjectAsObject refinement solves this problem (by Ruby's internal API without any manualy-emulated behavior).

# without refinement:
basic_obj = ::BasicObject.new

basic_obj.is_a?(::BasicObject) # raises ::NoMethodError
basic_obj.kind_of?(::BasicObject) # raises ::NoMethodError
basic_obj.instance_of?(::BasicObject) # rasies ::NoMethodError
basic_obj.freeze # raises ::NoMethodError
basic_obj.frozen? # raises ::NoMethodError
basic_object.hash # raises ::NoMethodError
basic_object.nil? # raises ::NoMethodError
basic_object.inspect # raises ::NoMethodError

# with refinement:
using SmartCore::Ext::BasicObjectAsObject

basic_obj = ::BasicObject.new

basic_obj.is_a?(::BasicObject) # => true
basic_obj.kind_of?(::BasicObject) # => true
basic_obj.instance_of?(::BasicObject) # => true
basic_obj.instance_of?(::Object) # => false
basic_obj.is_a?(::Integer) # => false
basic_obj.kind_of?(::Integer) # => false

basic_obj.frozen? # => false
basic_obj.freeze # => self
basic_obj.frozen? # => true

basic_obj.nil? # => false

basic_obj.hash # => 2682859680348634421 (some Integer value)

basic_obj.inspect # => "#<BasicObject:0x00007fe428018628>"

Inline rescue pipe

works with an array of proc objects;
returns the result of the first non-failed proc;
provides an error interception interface (a block argument);
fails with the last failed proc exception (if all procs were failed and interceptor was not passed);

Return the result of the first non-failed proc

SmartCore::Engine::RescueExt.inline_rescue_pipe(
  -> { raise },
  -> { raise },
  -> { 123 },
  -> { 567 },
  -> { raise },
)
# => output: 123

Fail with the last failed proc exception

SmartCore::Engine::RescueExt.inline_rescue_pipe(
  -> { raise(::ArgumentError) },
  -> { raise(::TypeError) },
  -> { raise(::ZeroDivisionError) }
)
# => fails with ZeroDivisionError

Error interception

SmartCore::Engine::RescueExt.inline_rescue_pipe(
  -> { raise(::ArgumentError) },
  -> { raise(::TypeError) },
  -> { raise(::ZeroDivisionError, 'Intercepted exception') }
) do |error|
  error.message
end
# => output: "Intercepted exception"

Roadmap

migrate to Github Actions in CI;
thread-safety for BasicObject extensions;
SmartCore::Engine::Cache:
- thread-safety;
- support for ttl: option for #write and for fallback block attribute of #read;
- support for key-value-pair iteration;
- support for #keys method;
- support for #key? method;
- think about some layer of cache object serialization;
SmartCore::Engine::ReadWriteLock:
- an ability to set a maximum count of readers;

Contributing

Fork it ( https://github.com/smart-rb/smart_engine )
Create your feature branch (git checkout -b feature/my-new-feature)
Commit your changes (git commit -am '[feature_context] Add some feature')
Push to the branch (git push origin feature/my-new-feature)
Create new Pull Request

License

Released under MIT License.

Supporting

Authors

Rustam Ibragimov

smart_engine

Development