.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "KiokuDB::Backend 3pm"
.TH KiokuDB::Backend 3pm "2014-03-25" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
KiokuDB::Backend \- Backend interface role
.SH "VERSION"
.IX Header "VERSION"
version 0.57
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    package KiokuDB::Backend::Foo;
\&    use Moose;
\&
\&    # load the core api and additional interfaces based on backend capabilities
\&    with qw(
\&        KiokuDB::Backend
\&
\&        KiokuDB::Backend::Role::TXN
\&        KiokuDB::Backend::Role::Clear
\&        KiokuDB::Backend::Role::Scan
\&        KiokuDB::Backend::Role::UnicodeSafe
\&        KiokuDB::Backend::Role::BinarySafe
\&    );
\&
\&    sub insert { ... }
\&
\&    sub get { ... }
\&
\&    sub delete { ... }
\&
\&    sub exists { ... }
\&
\&
\&
\&    # use the backend like this:
\&
\&    my $dir = KiokuDB\->new(
\&        backend => KiokuDB::Backend::Foo\->new( );
\&    );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
KiokuDB is designed to be fairly backend agnostic.
.PP
This role defines the minimal \s-1API\s0 for writing new backends.
.SH "TRANSACTIONS"
.IX Header "TRANSACTIONS"
This role is supplemented by KiokuDB::Backend::Role::TXN, a role for
first class transaction support that issues rollbacks using the
KiokuDB::Entry objects.
.SH "QUERYING"
.IX Header "QUERYING"
This role is supplemented by KiokuDB::Backend::Role::Query, a role for
backend specific queries.
.PP
KiokuDB::Backend::Role::Query::Simple provides a universal query api for
backends that can perform property based lookup.
.PP
KiokuDB::Backend::Role::Query::GIN is a role for using Search::GIN based
indexing/querying with backends that do not natively support querying.
.SH "REQUIRED METHODS"
.IX Header "REQUIRED METHODS"
.ie n .IP "get @ids" 4
.el .IP "get \f(CW@ids\fR" 4
.IX Item "get @ids"
Retrieve the KiokuDB::Entry objects associated with the \f(CW@ids\fR.
.Sp
If any other error is encountered, this method should die.
.Sp
The backend may store private data in \f(CW\*(C`backend_data\*(C'\fR, to be used in a subsequent update.
.Sp
Returns a list of KiokuDB::Entry, with the order corresponding to \f(CW@ids\fR.
If an entry does not exist then \f(CW\*(C`undef\*(C'\fR should be returned in place of it. The
backend may abort retrieval on the first non existent entry.
.ie n .IP "insert @entries" 4
.el .IP "insert \f(CW@entries\fR" 4
.IX Item "insert @entries"
Insert entries to the store.
.Sp
If the backend is transactional this operation should be atomic with respect to
the inserted/updated data.
.Sp
The backend is required to store the data in the fields \f(CW\*(C`data\*(C'\fR, \f(CW\*(C`class\*(C'\fR using
the key in \f(CW\*(C`id\*(C'\fR.
.Sp
Entries which have an entry in \f(CW\*(C`prev\*(C'\fR denote updates (either objects that have
been previously stored, or objects that were looked up). The previous entry may
be used to compare state for issuing a partial update, and will contain the
value of \f(CW\*(C`backend_data\*(C'\fR for any other state tracking.
.Sp
\&\f(CW\*(C`object\*(C'\fR is a weak reference to the object this entry is representing, and may
be used for high level indexing. Do not use this field for storage.
.Sp
If this backend implements some form of garbage collection, \f(CW\*(C`root\*(C'\fR denotes
that the objects is part of the root set.
.Sp
After all entries have been successfully written, \f(CW\*(C`backend_data\*(C'\fR should be set
if necessary just as in \f(CW\*(C`get\*(C'\fR.
.Sp
Has no return value.
.Sp
If \f(CW\*(C`insert\*(C'\fR does not die the write is assumed to be successful.
.ie n .IP "delete @ids_or_entries" 4
.el .IP "delete \f(CW@ids_or_entries\fR" 4
.IX Item "delete @ids_or_entries"
Delete the specified IDs or entries.
.Sp
If the user provided objects then entries will be passed in. Any associated
state the entries may have (e.g. a revision) should be used in order to enforce
atomicity with respect to the time when the objects were loaded.
.Sp
After all entries have been successfully deleted, \f(CW\*(C`deleted\*(C'\fR should be set. The
entry passed in is the same one as was loaded by \f(CW\*(C`get\*(C'\fR or last written by
\&\f(CW\*(C`insert\*(C'\fR, so it is already up to date in the live objects.
.Sp
Has no return value.
.Sp
If \f(CW\*(C`delete\*(C'\fR does not die the write is assumed to be successful.
.ie n .IP "exists @ids" 4
.el .IP "exists \f(CW@ids\fR" 4
.IX Item "exists @ids"
Check for existence of the specified IDs, without retrieving their data.
.Sp
Returns a list of true or false values.
.SH "METHODS"
.IX Header "METHODS"
These methods are provided by the KiokuDB::Backend role, and may be overridden.
.IP "new_from_dsn" 4
.IX Item "new_from_dsn"
Parses the second half of the \s-1DSN\s0 using \f(CW\*(C`parse_dsn_params\*(C'\fR and instantiates a
new object using \f(CW\*(C`new_from_dsn\*(C'\fR.
.Sp
See KiokuDB::Util.
.ie n .IP "new_from_dsn_params @args" 4
.el .IP "new_from_dsn_params \f(CW@args\fR" 4
.IX Item "new_from_dsn_params @args"
Takes \s-1DSN\s0 parameters and converts them to arguments suitable for \f(CW\*(C`new\*(C'\fR
.ie n .IP "parse_dsn_params $str" 4
.el .IP "parse_dsn_params \f(CW$str\fR" 4
.IX Item "parse_dsn_params $str"
The string is split on \f(CW\*(C`;\*(C'\fR to produce arguments. Arguments in the form
\&\f(CW\*(C`foo=bar\*(C'\fR are split on \f(CW\*(C`=\*(C'\fR into a key/value pair, and other arguments are
treated as a boolean key and returned as \f(CW\*(C`$arg => 1\*(C'\fR.
.SH "ADDITIONAL INTERFACES"
.IX Header "ADDITIONAL INTERFACES"
Your backend may include more roles, based on its capabilities.
.IP "KiokuDB::Backend::Serialize" 4
.IX Item "KiokuDB::Backend::Serialize"
.PD 0
.IP "KiokuDB::Backend::Serialize::Delegate" 4
.IX Item "KiokuDB::Backend::Serialize::Delegate"
.PD
For the actual serialization of entries, there are a number of serialization
roles.
.IP "KiokuDB::Backend::Role::Clear" 4
.IX Item "KiokuDB::Backend::Role::Clear"
\&\s-1API\s0 for clearing all entries.
.IP "KiokuDB::Backend::Role::Scan" 4
.IX Item "KiokuDB::Backend::Role::Scan"
\&\s-1API\s0 for enumerating entries.
.IP "KiokuDB::Backend::Role::BinarySafe" 4
.IX Item "KiokuDB::Backend::Role::BinarySafe"
.PD 0
.IP "KiokuDB::Backend::Role::UnicodeSafe" 4
.IX Item "KiokuDB::Backend::Role::UnicodeSafe"
.PD
If your serialization is able to store arbitrary binary data and/or unicode
strings, these informational roles should be included.
.IP "KiokuDB::Backend::Role::TXN" 4
.IX Item "KiokuDB::Backend::Role::TXN"
If your storage supports nested transactions (\f(CW\*(C`txn_begin\*(C'\fR, \f(CW\*(C`txn_commit\*(C'\fR etc)
this role provides the api to expose that functionality to the high level
KiokuDB api.
.IP "KiokuDB::Backend::Role::Query" 4
.IX Item "KiokuDB::Backend::Role::Query"
.PD 0
.IP "KiokuDB::Backend::Role::Query::GIN" 4
.IX Item "KiokuDB::Backend::Role::Query::GIN"
.PD
If your backend supports querying of some sort, these are the roles to include.
.Sp
The querying \s-1API\s0 uses backend specific lookups to fetch entries, which
KiokuDB will then relink into result objects.
.SH "SHARED BACKENDS"
.IX Header "SHARED BACKENDS"
A backend may be shared by several KiokuDB instances, each with its own
distinct live object set. The backend may choose to share cached entry \fBdata\fR,
as that is not mutated by KiokuDB::Linker, but not the KiokuDB::Entry
instances themselves.
.SH "AUTHOR"
.IX Header "AUTHOR"
Yuval Kogman <nothingmuch@woobling.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2014 by Yuval Kogman, Infinity Interactive.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.