Darren Duncan > Muldis-Rosetta > Muldis::Rosetta::Interface

Download:
Muldis-Rosetta-0.16.0.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

Open  1
View/Report Bugs
Module Version: 0.016000   Source  

NAME ^

Muldis::Rosetta::Interface - Common public API for Muldis Rosetta Engines

VERSION ^

This document describes Muldis::Rosetta::Interface version 0.16.0 for Perl 5.

It also describes the same-number versions for Perl 5 of Muldis::Rosetta::Interface::Machine ("Machine"), Muldis::Rosetta::Interface::Process ("Process"), Muldis::Rosetta::Interface::Value ("Value").

SYNOPSIS ^

This simple example declares two Perl variables containing relation data, then does a (N-adic) relational join (natural inner join) on them, producing a third Perl variable holding the relation data of the result.

    use Muldis::Rosetta::Engine::Example;
    my $machine = Muldis::Rosetta::Engine::Example::select_machine();

    my $process = $machine->new_process();
    $process->update_hd_command_lang({ 'lang' => [ 'Muldis_D',
        'http://muldis.com', '0.110.0', 'HDMD_Perl5_STD',
        { catalog_abstraction_level => 'rtn_inv_alt_syn',
        op_char_repertoire => 'extended' } ] });

    my $r1 = $process->new_value({
        'source_code' => [ 'Relation', [ [ 'x', 'y' ] => [
            [ 4, 7 ],
            [ 3, 2 ],
        ] ] ]
    });

    my $r2 = $process->new_value({
        'source_code' => [ 'Relation', [ [ 'y', 'z' ] => [
            [ 5, 6 ],
            [ 2, 1 ],
            [ 2, 4 ],
        ] ] ]
    });

    my $r3 = $process->func_invo({
        'function' => 'join',
        'args' => {
            'topic' => [ 'Set', [ $r1, $r2 ] ],
        }
    });

    my $r3_as_perl = $r3->hd_source_code();

    # Then $r3_as_perl contains:
    # [ 'Relation', [ [ 'x', 'y', 'z' ] => [
    #     [ 3, 2, 1 ],
    #     [ 3, 2, 4 ],
    # ] ] ]

If the name of the Muldis Rosetta Engine to use is being read from a config file, as $engine_name, rather than being hard-coded into the application, then these next 2 lines can be used instead of the first 2 lines above, assuming the Class::MOP module is already loaded:

    Class::MOP::load_class( $engine_name );
    my $machine = &{$engine_name->can( 'select_machine' )}();

For most examples of using Muldis Rosetta, and tutorials, please see the separate Muldis::D::Manual.

DESCRIPTION ^

Muldis::Rosetta::Interface, aka Interface, comprises the minimal core of the Muldis Rosetta framework, the one component that probably every program would use. Together with the Muldis D language (see Muldis::D), it defines the common API for Muldis Rosetta implementations to do and which applications invoke.

This documentation is pending.

INTERFACE ^

The interface of Muldis::Rosetta::Interface is fundamentally object-oriented; you use it by creating objects from its member classes (or more specifically, of implementing classes that compose its member roles) and then invoking methods on those objects. All of their attributes are private, so you must use accessor methods.

To aid portability of your applications over multiple implementing Engines, the normal way to create Interface objects is by invoking a constructor-wrapping method of some other object that would provide context for it; since you generally don't have to directly invoke any package names, you don't need to change your code when the package names change due to switching the Engine. You only refer to some Engine's root package name once, as the namespace on which you invoke the select_machine constructor function, and even that can be read from a config file rather than being hard-coded in your application.

The usual way that Muldis::Rosetta::Interface indicates a failure is to throw an exception; most often this is due to invalid input. If an invoked routine simply returns, you can assume that it has succeeded, even if the return value is undefined.

The Root Package of a Muldis Rosetta Engine ^

A Perl module that is a Muldis Rosetta Engine is expected to be implemented with a public API consisting of one stateless root package plus several classes. The stateless root package is what by way of which you access the whole Muldis Rosetta API; that is, you use it to instantiate virtual machines, which provide the rest of the Muldis Rosetta API. The root package is expected to have the same Perl package name as the conceptual Perl package name of the whole Engine; for example, the Engine named Muldis::Rosetta::Engine::Example is expected to declare a package named Muldis::Rosetta::Engine::Example as its root package. There is no strict requirement on what the other API-providing classes of the Engine are named, especially since in general any users of the Engine would never be referencing objects of theirs by name; however, best practice would have them living in child namespaces of the Engine root package, for example Muldis::Rosetta::Engine::Example::Public::Machine.

The root package of a Muldis Rosetta Engine is expected to declare a select_machine constructor function, as described next.

select_machine

sub select_machine of Muldis::Rosetta::Interface::Machine ()

This constructor function selects (first creating if necessary) and returns the singleton Machine object that is implemented by the Muldis Rosetta Engine whose stateless root package name it is invoked on. This constructor function is expected to return an object of some class of the same Engine which does the Muldis::Rosetta::Interface::Machine role.

The Muldis::Rosetta::Interface::Machine Role ^

A Machine object represents a single active Muldis Rosetta virtual machine / Muldis D environment, which is the widest scope stateful context in which any other database activities happen. Other activities meaning the compilation and execution of Muldis D code, mounting or unmounting depots, performing queries, data manipulation, data definition, and transactions. It is expected that a Muldis Rosetta Engine would implement a Machine as a singleton (or behave as if it did), so only one such object would exist at a time in a Perl process per distinct Engine, in which case a Machine would be a proxy for the Engine as a whole, by which one can act on the Engine in a "global" sense. If a Machine object is ever garbage collected by Perl while it has any active transactions, then those will all be rolled back, and then an exception thrown.

new_process

method new_process of Muldis::Rosetta::Interface::Process ($self: Hash :$process_config?)

This method creates and returns a new Process object that is associated with the invocant Machine; that Process object is initialized using the $process_config argument.

The Muldis::Rosetta::Interface::Process Role ^

A Process object represents a single Muldis Rosetta in-DBMS process, which has its own autonomous transactional context, and for the most part, its own isolated environment. It is associated with a specific Machine object, the one whose new_process method created it.

A new Process object's "expected plain-text|Perl-hosted-data command language" attribute is undefined by default, meaning that each plain-text|Perl-hosted-data command fed to the process must declare what plain-text|Perl-hosted-data language it is written in; if that attribute was made defined, then plain-text|Perl-hosted-data commands fed to it would not need to declare their plain-text|Perl-hosted-data language and will be interpreted according to the expected plain-text|Perl-hosted-data language; if both the attribute is defined and the command has its own language declaration, then the one with the command will override the attribute.

assoc_machine

method assoc_machine of Muldis::Rosetta::Interface::Machine ($self:)

This method returns the Machine object that the invocant Process is associated with.

pt_command_lang

method pt_command_lang of Str ($self:)

This method returns the fully qualified name of its invocant Process object's "expected plain-text command language" attribute, which might be undefined; if it is defined, then is a Perl Str that names a Plain Text language; these may be Muldis D dialects or some other language.

update_pt_command_lang

method update_pt_command_lang ($self: Str :$lang!)

This method assigns a new (possibly undefined) value to its invocant Process object's "expected plain-text command language" attribute. This method dies if the specified language is defined and its value isn't one that the invocant's Engine knows how to or desires to handle.

hd_command_lang

method hd_command_lang of Array ($self:)

This method returns the fully qualified name of its invocant Process object's "expected Perl-hosted-data command language" attribute, which might be undefined; if it is defined, then is a Perl (ordered) Array that names a Perl Hosted Data language; these may be Muldis D dialects or some other language.

update_hd_command_lang

method update_hd_command_lang ($self: Array :$lang!)

This method assigns a new (possibly undefined) value to its invocant Process object's "expected Perl-hosted-data command language" attribute. This method dies if the specified language is defined and its value isn't one that the invocant's Engine knows how to or desires to handle.

execute

method execute ($self: Any :$source_code!, Any :$lang?)

This method compiles and executes the (typically Muldis D) source code given in its $source_code argument. If $source_code is a Perl Str then it is treated as being written in a plain-text language; if $source_code is any kind of Perl 5 reference or Perl 5 object then it is treated as being written in a Perl-hosted-data language. This method dies if the source code fails to compile for some reason, or if the executing code has a runtime exception. If $lang is defined, it must match $source_code in Str vs Array|obj categorization.

new_value

method new_value of Muldis::Rosetta::Interface::Value ($self: Any :$source_code!, Any :$lang?)

This method creates and returns a new Value object that is associated with the invocant Process; that Value object is initialized using the (typically Muldis D) source code given in its $source_code argument, which defines a value literal. If $source_code is a Perl Str then it is treated as being written in a plain-text language; if $source_code is any kind of Perl 5 reference or Perl 5 object then it is treated as being written in a Perl-hosted-data language. If the $source_code is in a Perl Hosted Data language, then it may consist partially of other Value objects. If $source_code is itself just a Value object, then it will be cloned. Because a source code fragment representing a value literal typically doesn't embed its own declaration of the plain-text|Perl-hosted-data language it is written in, that language must be specified external to the fragment, either by giving a defined $lang argument, or by ensuring that the invocant Process object has a defined "expected plain-text|Perl-hosted-data command language" attribute. If $lang is defined, it must match $source_code in Str vs Array|obj categorization.

func_invo

method func_invo of Muldis::Rosetta::Interface::Value ($self: Str :$function!, Hash :$args?, Str :$pt_lang?, Array :$hd_lang?)

This method invokes the Muldis D function named by its $function argument, giving it arguments from $args, and then returning the result as a Value object. Each $args Hash key must match the name of a parameter of the named function, and the corresponding Hash value is the argument for that parameter; each Hash value may be either a Value object or some other Perl value that would be suitable as the $source_code constructor argument for a new Value object; if $pt_lang or $hd_lang are defined, the appropriate one will be given as the $lang constructor argument.

upd_invo

method upd_invo ($self: Str :$updater!, Hash :$upd_args!, Hash :$ro_args?, Str :$pt_lang?, Array :$hd_lang?)

This method invokes the Muldis D updater named by its $updater argument, giving it subject-to-update arguments from $upd_args and read-only arguments from $ro_args; the Value objects in $upd_args are possibly substituted for other Value objects as a side-effect of the updater's execution. The $ro_args parameter is as per the $args parameter of the func_invo method, but the $upd_args parameter is a bit different; each Hash value in the $upd_args argument must be a Perl scalar reference pointing to the Perl variable being bound to the subject-to-update parameter; said Perl variable is then what holds a Value object et al prior to the updater's execution, and that may have been updated to hold a different Value object as a side-effect.

proc_invo

method proc_invo ($self: Str :$procedure!, Hash :$upd_args?, Hash :$ro_args?, Str :$pt_lang?, Array :$hd_lang?)

This method invokes the Muldis D procedure named by its $procedure argument, giving it subject-to-update arguments from $upd_args and read-only arguments from $ro_args; the Value objects in $upd_args are possibly substituted for other Value objects as a side-effect of the procedure's execution. The parameters of proc_invo are as per those of the upd_invo method, save that only upd_invo makes $upd_args mandatory, while proc_invo makes it optional.

trans_nest_level

method trans_nest_level of Int ($self:)

This method returns the current transaction nesting level of its invocant's virtual machine process. If no explicit transactions were started, then the nesting level is zero, in which case the process is conceptually auto-committing every successful Muldis D statement. Each call of start_trans will increase the nesting level by one, and each commit_trans or rollback_trans will decrease it by one (it can't be decreased below zero). Note that all transactions started or ended within Muldis D code are attached to a particular lexical scope in the Muldis D code, and so they will never have any effect on the nest level that Perl sees (assuming that a Muldis D host language will never be invoked by Muldis D), regardless of whether the Muldis D code successfully returns or throws an exception.

start_trans

method start_trans ($self:)

This method starts a new child-most transaction within the invocant's virtual machine process.

commit_trans

method commit_trans ($self:)

This method commits the child-most transaction within the invocant's virtual machine process; it dies if there isn't one.

rollback_trans

method rollback_trans ($self:)

This method rolls back the child-most transaction within the invocant's virtual machine process; it dies if there isn't one.

The Muldis::Rosetta::Interface::Value Role ^

A Value object represents a single Muldis Rosetta in-DBMS value, which is conceptually immutable, eternal, and not fixed in time or space; the object is immutable. It is associated with a specific Process object, the one whose new_value method created it. You can use Value objects in Perl routines the same as normal immutable Perl values or objects, including that you just do ordinary Perl variable assignment. Value objects are the normal way to directly share or move data between the Muldis Rosetta DBMS and main Perl environments. The value that a Value object represents is set when the Value object is created, and it can't be changed afterwards.

assoc_process

method assoc_process of Muldis::Rosetta::Interface::Process ($self:)

This method returns the Process object that the invocant Value is associated with.

pt_source_code

method pt_source_code of Str ($self: Str :$lang?)

This method returns (typically Muldis D) plain-text source code that defines a value literal equivalent to the in-DBMS value that the invocant Value represents. The plain-text language of the source code to return must be explicitly specified, either by giving a defined $lang argument, or by ensuring that the Process object associated with this Value has a defined "expected plain-text command language" attribute.

hd_source_code

method hd_source_code of Any ($self: Array :$lang?)

This method returns (typically Muldis D) Perl-hosted-data source code that defines a value literal equivalent to the in-DBMS value that the invocant Value represents. The Perl-hosted-data language of the source code to return must be explicitly specified, either by giving a defined $lang argument, or by ensuring that the Process object associated with this Value has a defined "expected Perl-hosted-data command language" attribute.

DIAGNOSTICS ^

This documentation is pending.

CONFIGURATION AND ENVIRONMENT ^

This documentation is pending.

DEPENDENCIES ^

This file 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::Role-ver(0.98..*).

INCOMPATIBILITIES ^

None reported.

SEE ALSO ^

Go to Muldis::Rosetta for the majority of distribution-internal references, and Muldis::Rosetta::SeeAlso for the majority of distribution-external references.

BUGS AND LIMITATIONS ^

The Muldis Rosetta framework for Perl 5 does not make explicit attempts in code to enforce privacy of the framework's internals, besides not documenting them as part of the public API. (The Muldis Rosetta framework for Perl 6 is different.) That said, you should still respect that privacy and just use the public API that Muldis Rosetta provides. If you bypass the public API anyway, as Perl 5 allows, you do so at your own peril.

This documentation is pending.

AUTHOR ^

Darren Duncan (darren@DarrenDuncan.net)

LICENSE AND COPYRIGHT ^

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.

TRADEMARK POLICY ^

The TRADEMARK POLICY in Muldis::Rosetta applies to this file too.

ACKNOWLEDGEMENTS ^

The ACKNOWLEDGEMENTS in Muldis::Rosetta apply to this file too.

syntax highlighting: