Muldis::Rosetta::Engine::Example - Self-contained reference implementation of a Muldis Rosetta Engine
This document describes Muldis::Rosetta::Engine::Example version 0.16.0 for Perl 5.
It also describes the same-number versions for Perl 5 of Muldis::Rosetta::Engine::Example::Public::Machine, Muldis::Rosetta::Engine::Example::Public::Process, Muldis::Rosetta::Engine::Example::Public::Value.
This documentation is pending.
Muldis::Rosetta::Engine::Example, aka the Muldis Rosetta Example Engine, aka Example, is the self-contained and pure-Perl reference implementation of Muldis Rosetta. It is included in the Muldis Rosetta core distribution to allow the core to be completely testable on its own.
Example is coded intentionally in a simple fashion so that it is easy to maintain and easy for developers to study. As a result, while it performs correctly and reliably, it also performs quite slowly; you should only use Example for testing, development, and study; you should not use it in production. (See the Muldis::Rosetta::SeeAlso file for a list of other Engines that are more suitable for production.)
This Muldis::Rosetta::Engine::Example file is the main file of the Example Engine, and it is what applications quasi-directly invoke; its Muldis::Rosetta::Engine::Example::Public::\w+ classes directly do/compose the roles in Muldis::Rosetta::Interface. The other Muldis::Rosetta::Engine::Example::\w+ files are used internally by this file, comprising the rest of the Example Engine, and are not intended to be used directly in user code.
Muldis::Rosetta::Engine::Example
Muldis::Rosetta::Engine::Example::Public::\w+
Muldis::Rosetta::Engine::Example::\w+
Example, loosely speaking, uses the SQLite DBMS as a model for implementation. Example uses a single file on disk to represent an entire persisting depot, including all of its schemata and data, and users may store this file anywhere they want and with any name they want (subject to filesystem limitations); Example does not store a collection of multiple files in a fixed location like most large DBMSs. Example will create a temporary rollback journal file for a depot when it is about to write changes to the depot file, though unlike SQLite this journal is actually just a copy of the entire file, not just the portions that are being changed.
There are some intentional design decisions of Example that significantly impact performance or scalability but don't impact behaviour, which are listed next; it is not expected these will be changed, due to Example's intended use for testing and learning, to keep it simple, though they might end up being changed anyway if the simplicity goal of Example isn't compromosed in the process:
Example is fundamentally a RAM-based DBMS; any temporary (RAM-based) depot represents Example's native way of doing things most faithfully, as it is just a tree of ordinary Perl objects. Any persisting (disk-file-based) depot is loaded entirely into RAM when mounted and deserialized into such a tree of Perl objects, where it then lives like a temporary depot; when a parent-most transaction commits with changes to the loaded depot, then the entire depot is serialized and the entire disk file is rewritten over (but a typical rollback has essentially no cost). So the maximum size of any Example depot is limited to what can entirely fit in RAM when not serialized. It also stands to reason in general that aggregating many updates into a single parent-most transaction will perform better than committing each one separately, since then only one rewrite to disk would occur.
Access to the same disk-file-based depot by multiple Perl processes will be mediated by whole-file locks; multiple Perl processes may have readonly access to the same file at once, but only one Perl process may have write access at once, when it is the only process with a lock on the file; different Perl processes can not get locks on different parts of the same file at once in order to do non-conflicting updates. That said, some tasks can be made more efficient by utilizing multiple in-DBMS processes within a single Perl process, rather than single in-DBMS processes within multiple Perl processes. One reason is that all in-DBMS processes of a common Perl process will cooperate on actual access to a single file, and can make non-conflicting updates at once; moreover, a depot is only loaded into RAM once to be shared by all inner processes. In other words, wrapping up an Example Machine object in a DBMS server Perl process with multiple clients may improve concurrency for some tasks.
Every in-DBMS value, whether simple or complex, is represented by a mostly immutable object tree. No value objects are updated in place; any operation that would derive a new value from an old one will create a new value object and the old one will be left alone; this is even true for collection values like tuples or relations; this means copy-on-write by default. The resulting semantics are that to some extent the DBMS is multi-versioned; anyone referencing an object can conceptually update it while others that hold it continue to have a consistent view; we get safety simply. Its also easier to support nested transactions and rollbacks; a rollback just means discarding a newly derived value and using the previous one. While some explicit concurrency management is necessary, such as when one makes a change to a depot they want to commit, a lot of work is saved. The main trade-off here is that updates of large collections like a relvar might be slower though possibly not.
Example will default to doing most operations with brute force by default if that is the simplest way to code them up; but some indexes/etc will be used where a lot of gain can be had for little coding effort.
Muldis::Rosetta::Engine::Example supports multiple command languages, all of which are official Muldis D dialects. You may supply commands to Example written in any of the following:
See Muldis::D::Dialect::PTMD_STD for details.
The language name is specified as a Perl character string whose value is Muldis_D:"http://muldis.com":0.110.0:PTMD_STD:{...}. No other version numbers are currently supported. All options defined by PTMD_STD for its ln_extensions 5th name element are supported.
Muldis_D:"http://muldis.com":0.110.0:PTMD_STD:{...}
ln_extensions
See Muldis::D::Dialect::HDMD_Perl5_STD for details.
The language name is specified as a Perl array whose value is [ 'Muldis_D', 'http://muldis.com', '0.110.0', 'HDMD_Perl5_STD', {...} ]. No other version numbers are currently supported. All options defined by HDMD_Perl5_STD for its ln_extensions 5th name element are supported.
[ 'Muldis_D', 'http://muldis.com', '0.110.0', 'HDMD_Perl5_STD', {...} ]
You may also supply or retrieve data through Example in any of the above.
The Muldis Rosetta Example Engine, meaning the collection of files that includes this file and all other Muldis::Rosetta::Engine::Example::\w+ files, requires any version of Perl 5.x.y that is at least 5.8.1, and recommends one that is at least 5.10.1.
It also requires these Perl 5 packages that are on CPAN: namespace::autoclean-ver(0.09..*), Moose-ver(0.98..*), Moose::Role-ver(0.98..*), MooseX::Singleton-ver(0.22..*).
It also requires these Perl 5 packages that are in the current distribution: Muldis::Rosetta::Interface-ver(0.16.0..*).
None reported.
Go to Muldis::Rosetta for the majority of distribution-internal references, and Muldis::Rosetta::SeeAlso for the majority of distribution-external references.
Although Muldis::Rosetta::Engine::Example is supposed to implement the features and semantics of the entire Muldis D language, it has several limitations which are not expected to be surmounted in the short term, due to intentional design decisions for speeding development; but they are expected to be addressed in the longer term:
Each in-DBMS process may have no more than one depot mount at any given time whose is_temporary flag is false and whose we_may_update flag is true; in other words, atomic commits against multiple persistent (disk-file-based) depots are not yet supported. However, in addition to one such depot mount, any number of updateable temporary (RAM-based) depot mounts or read-only persistent (disk-file-based) depot mounts may exist in a single in-DBMS process at once. So the most common DBMS usage scenarios should still be supported.
is_temporary
we_may_update
If any existing Example feature/behaviour limitations are not listed in this file, then they are expected to be addressed in the short term.
Darren Duncan (darren@DarrenDuncan.net)
darren@DarrenDuncan.net
This file is part of the Muldis Rosetta framework.
Muldis Rosetta is Copyright © 2002-2010, Muldis Data Systems, Inc.
See the LICENSE AND COPYRIGHT of Muldis::Rosetta for details.
The TRADEMARK POLICY in Muldis::Rosetta applies to this file too.
The ACKNOWLEDGEMENTS in Muldis::Rosetta apply to this file too.
To install Muldis::Rosetta, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Muldis::Rosetta
CPAN shell
perl -MCPAN -e shell install Muldis::Rosetta
For more information on module installation, please visit the detailed CPAN module installation guide.