NAME

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

VERSION

This document describes Muldis::DB::Interface version 0.4.0 for Perl 5.

It also describes the same-number versions for Perl 5 of Muldis::DB::Interface::DBMS (``DBMS''), Muldis::DB::Interface::Var (``Var''), Muldis::DB::Interface::FuncBinding (``FuncBinding''), and Muldis::DB::Interface::ProcBinding (``ProcBinding'').

SYNOPSIS

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

    use Muldis::DB::Interface;

    my $dbms = Muldis::DB::Interface::new_dbms({
        'engine_name' => 'Muldis::DB::Engine::Example',
        'dbms_config' => {},
    });

    my $r1 = $dbms->new_var({
        'decl_type' => 'sys.Core.Relation.Relation' });
    my $r2 = $dbms->new_var({
        'decl_type' => 'sys.Core.Relation.Relation' });

    $r1->store_ast({ 'ast' => [ 'Relation', 'sys.Core.Relation.Relation', [
        {
            'x' => [ 'PInt', 'perl_pint', 4 ],
            'y' => [ 'PInt', 'perl_pint', 7 ],
        },
        {
            'x' => [ 'PInt', 'perl_pint', 3 ],
            'y' => [ 'PInt', 'perl_pint', 2 ],
        },
    ] ] });

    $r2->store_ast({ 'ast' => [ 'Relation', 'sys.Core.Relation.Relation', [
        {
            'y' => [ 'PInt', 'perl_pint', 5 ],
            'z' => [ 'PInt', 'perl_pint', 6 ],
        },
        {
            'y' => [ 'PInt', 'perl_pint', 2 ],
            'z' => [ 'PInt', 'perl_pint', 1 ],
        },
        {
            'y' => [ 'PInt', 'perl_pint', 2 ],
            'z' => [ 'PInt', 'perl_pint', 4 ],
        },
    ] ] });

    my $r3 = $dbms->call_func(
        'func_name' => 'sys.Core.Relation.join',
        'args' => {
            'topic' => [ 'QuasiSet', 'sys.Core.Spec.QuasiSetOfRelation', [
                $r1,
                $r2,
            ],
        }
    );

    my $r3_ast = $r3->fetch_ast();

    # Then $r3_ast contains:
    # [ 'Relation', 'sys.Core.Relation.Relation', [
    #     {
    #         'x' => [ 'PInt', 'perl_pint', 3 ],
    #         'y' => [ 'PInt', 'perl_pint', 2 ],
    #         'z' => [ 'PInt', 'perl_pint', 1 ],
    #     },
    #     {
    #         'x' => [ 'PInt', 'perl_pint', 3 ],
    #         'y' => [ 'PInt', 'perl_pint', 2 ],
    #         'z' => [ 'PInt', 'perl_pint', 4 ],
    #     },
    # ] ]

For most examples of using Muldis DB, and tutorials, please see the separate the Muldis::DB::Cookbook manpage distribution (when that comes to exist).

DESCRIPTION

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

This documentation is pending.

INTERFACE

The interface of Muldis::DB::Interface is fundamentally object-oriented; you use it by creating objects from its member classes (or more specifically, of implementing subclasses of 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 a Muldis::DB::Interface::new_dbms argument, and even that can be read from a config file rather than being hard-coded in your application.

The usual way that Muldis::DB::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 Muldis::DB::Interface Module

The Muldis::DB::Interface module is the stateless root package by way of which you access the whole Muldis DB API. That is, you use it to load engines and instantiate virtual machines, which provide the rest of the Muldis DB API.

new_dbms of Muldis::DB::Interface::DBMS (Str :$engine_name!, Any :$dbms_config!): This constructor function creates and returns a DBMS object that is implemented by the Muldis DB Engine named by its named argument $engine_name; that object is initialized using the $dbms_config argument. The named argument $engine_name is the name of a Perl module that is expected to be the root package of a Muldis DB Engine, and which is expected to declare a new_dbms subroutine with a single named argument $dbms_config; invoking this subroutine is expected to return an object of some class of the same Engine which does the Muldis::DB::Interface::DBMS role. This function will start by testing if the root package is already loaded (it may be declared by some already-loaded file of another name), and only if not, will it do a Perl 'require' of the $engine_name.

The Muldis::DB::Interface::DBMS Role

A DBMS object represents a single active Muldis DB 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. If a DBMS 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_var of Muldis::DB::Interface::Var (Str :$decl_type!): This method creates and returns a new Var object that is associated with the invocant DBMS, and whose declared Muldis D type is named by the $decl_type argument, and whose default Muldis D value is the default value of its declared type.
assoc_vars of Array (): This method returns, as elements of a new (unordered) Array, all the currently existing Var objects that are associated with the invocant DBMS.
new_func_binding of Muldis::DB::Interface::FuncBinding (): This method creates and returns a new FuncBinding object that is associated with the invocant DBMS.
assoc_func_bindings of Array (): This method returns, as elements of a new (unordered) Array, all the currently existing FuncBinding objects that are associated with the invocant DBMS.
new_proc_binding of Muldis::DB::Interface::ProcBinding (): This method creates and returns a new ProcBinding object that is associated with the invocant DBMS.
assoc_proc_bindings of Array (): This method returns, as elements of a new (unordered) Array, all the currently existing ProcBinding objects that are associated with the invocant DBMS.
call_func of Muldis::DB::Interface::Var (Str :$func_name!, Hash :$args!): This method invokes the Muldis D function named by its $func_name argument, giving it arguments from $args, and then returning the result as a new Var object. This method is conceptually a wrapper over the creation of a FuncBinding object, setting up its bindings, and invoking its call method.
call_proc (Str :$proc_name!, Hash :$upd_args!, Hash :$ro_args!): This method invokes the Muldis D procedure named by its $proc_name argument, giving it subject-to-update arguments from $upd_args and read-only arguments from $ro_args; the Var objects in $upd_args are possibly updated as a side-effect of the procedure's execution. This method is conceptually a wrapper over the creation of a ProcBinding object, setting up its bindings, and invoking its call method.
trans_nest_level of Int (): This method returns the current transaction nesting level of its invocant's virtual machine. If no explicit transactions were started, then the nesting level is zero, in which case the DBMS 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 (specifically a ``try/catch'' context), 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 (): This method starts a new child-most transaction within the invocant's virtual machine.
commit_trans (): This method commits the child-most transaction within the invocant's virtual machine; it dies if there isn't one.
rollback_trans (): This method rolls back the child-most transaction within the invocant's virtual machine; it dies if there isn't one.

The Muldis::DB::Interface::Var Role

A Var object is a Muldis D variable that is lexically scoped to the Perl environment (like an ordinary Perl variable). It is associated with a specific DBMS object, the one whose new_var method created it, but it is considered anonymous and non-invokable within the virtual machine. The only way for Muldis D code to work with these variables is if they bound to Perl invocations of Muldis D routines being call(|\w+) by Perl; a Muldis D routine parameter one is bound to is the name it is referenced by in the virtual machine. Var objects are the normal way to directly share or move data between the Muldis D and Perl environments. A Var is strongly typed, and the declared Muldis D type of the variable (which affects what values it is allowed to hold) is set when the Var object is created, and this declared type can't be changed afterwards.

assoc_dbms of Muldis::DB::Interface::DBMS (): This method returns the DBMS object that the invocant Var is associated with.
decl_type of Str (): This method returns the declared Muldis D type of its invocant Var.
fetch_ast of Array (): This method returns the current Muldis D value of its invocant Var as a Perl Hosted Abstract Muldis D data structure (whose root node is a Perl Array).
store_ast (Array :$ast!): This method assigns a new Muldis D value to its invocant Var, which is supplied in the $ast argument; the argument is expected to be a valid Perl Hosted Abstract Muldis D data structure (whose root node is a Perl Array).

The Muldis::DB::Interface::FuncBinding Role

A FuncBinding represents a single Muldis D function that may be directly invoked by Perl code. It is associated with a specific DBMS object, the one whose new_func_binding method created it, and the function it represents lives in and has a global-public scoped name in the corresponding virtual machine. This is specifically a lazy binding, so no validity checking of the object happens except while the FuncBinding's call method is being executed, and a then-valid object can then become invalid afterwards. A FuncBinding is conceptually used behind the scenes to implement a DBMS object's call_func method, but you can use it directly instead, for possibly better performance.

assoc_dbms of Muldis::DB::Interface::DBMS (): This method returns the DBMS object that the invocant FuncBinding is associated with.
bind_func (Str :$func_name!): This method causes the invocant FuncBinding to be associated with the Muldis D function named by the $func_name argument.
bound_func of Str (): This method returns the name of the Muldis D function that the invocant FuncBinding is currently associated with, or undef if that wasn't set.
bind_result (Muldis::DB::Interface::Var :$var!): This method binds the Var object in $var to the result of the Muldis D function associated with the invocant FuncBinding; when the function is executed via the FuncBinding, its result will end up in $var.
bound_result of Muldis::DB::Interface::Var (): This method returns the Var object currently bound to the function result.
bind_params (Hash :$args!): This method binds the Var objects that are the Hash values in $args to the parameters of the Muldis D function such that they correspond by Hash key names matching parameter names; when the function is executed via the FuncBinding, its arguments are pulled from the $args. Note that the same Var object may be bound to multiple parameters and/or the result at once. This method alternately allows a Perl Array which is Perl Hosted Muldis D to be supplied instead of any given Var object, in which case a new Var object will be non-lazily created with that value, and be used there.
bound_params of Hash (): This method returns, as values of a new Hash, the Var objects currently bound to the function's parameters, with the corresponding Hash keys being the names of the parameters they are bound to.
call (): This method performs any lazy validation on the invocant FuncBinding, and with no failure, it then invokes the Muldis D function. It is at this time that the current values of any bound Var objects are taken.

The Muldis::DB::Interface::ProcBinding Role

A ProcBinding represents a single Muldis D procedure that may be directly invoked by Perl code. It is associated with a specific DBMS object, the one whose new_proc_binding method created it, and the procedure it represents lives in and has a global-public scoped name in the corresponding virtual machine. This is specifically a lazy binding, so no validity checking of the object happens except while the ProcBinding's call method is being executed, and a then-valid object can then become invalid afterwards. A ProcBinding is conceptually used behind the scenes to implement a DBMS object's call_proc method, but you can use it directly instead, for possibly better performance.

assoc_dbms of Muldis::DB::Interface::DBMS (): This method returns the DBMS object that the invocant ProcBinding is associated with.
bind_proc (Str :$proc_name!): This method causes the invocant ProcBinding to be associated with the Muldis D procedure named by the $proc_name argument.
bound_proc of Str (): This method returns the name of the Muldis D procedure that the invocant ProcBinding is currently associated with, or undef if that wasn't set.
bind_upd_params (Hash :$args!): This method binds the Var objects that are the Hash values in $args to the subject-to-update parameters of the Muldis D procedure such that they correspond by Hash key names matching parameter names; when the procedure is executed via the ProcBinding, its subject-to-update arguments (if they would be used) are pulled from the $args, and resulting values are written to them (if applicable).
bound_upd_params of Hash (): This method returns, as values of a new Hash, the Var objects currently bound to the procedure's subject-to-update parameters, with the corresponding Hash keys being the names of the parameters they are bound to.
bind_ro_params (Hash :$args!): This method binds the Var objects that are the Hash values in $args to the read-only parameters of the Muldis D procedure such that they correspond by Hash key names matching parameter names; when the procedure is executed via the ProcBinding, its read-only arguments are pulled from the $args. Note that the same Var object may be bound to multiple parameters and/or the result at once. This method alternately allows a Perl Array which is Perl Hosted Muldis D to be supplied instead of any given Var object, in which case a new Var object will be non-lazily created with that value, and be used there.
bound_ro_params of Hash (): This method returns, as values of a new Hash, the Var objects currently bound to the procedure's read-only parameters, with the corresponding Hash keys being the names of the parameters they are bound to.
call (): This method performs any lazy validation on the invocant ProcBinding, and with no failure, it then invokes the Muldis D procedure. It is at this time that the current values of any bound Var objects are taken.

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.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

The Muldis DB framework for Perl 5 is built according to certain old-school or traditional Perl-5-land design principles, including that there are no explicit attempts in code to enforce privacy of the framework's internals, besides not documenting them as part of the public API. (The Muldis DB framework for Perl 6 is different.) That said, you should still respect that privacy and just use the public API that Muldis DB 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 (perl@DarrenDuncan.net)

LICENSE AND COPYRIGHT

This file is part of the Muldis DB framework.

See the LICENSE AND COPYRIGHT of the Muldis::DB manpage for details.

ACKNOWLEDGEMENTS

The ACKNOWLEDGEMENTS in the Muldis::DB manpage apply to this file too.

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