NAME
SYNOPSIS
DESCRIPTION
- Subclassing
CONSTRUCTOR
- new
DESTRUCTOR
- DESTROY
METHODS
- to_string
COPYRIGHT
LICENSE, DISCLAIMER, BUGS, etc.

NAME

KinoSearch::Obj - Base class for all KinoSearch objects.

SYNOPSIS

    package MyObj;
    use base qw( KinoSearch::Obj );

    # Inside-out member var.
    my %foo;

    sub new {
        my ( $class, %args ) = @_;
        my $foo = delete $args{foo};
        my $self = $class->SUPER::new(%args);
        $foo{$$self} = $foo;
        return $self;
    }

    sub DESTROY {
        my $self = shift;
        delete $foo{$$self};
        $self->SUPER::DESTROY;
    }

DESCRIPTION

All objects in the KinoSearch:: hierarchy descend from KinoSearch::Obj. All classes are implemented as blessed scalar references, with the scalar storing a pointer to a C struct.

Subclassing

The recommended way to subclass KinoSearch::Obj and its descendants is to use the inside-out pattern. (See Class::InsideOut for an introduction to inside-out techniques.)

Since the blessed scalar stores a C pointer value which is unique per-object, $$self can be used as an inside-out ID.

    # Accessor for 'foo' member variable.
    sub get_foo {
        my $self = shift;
        return $foo{$$self};
    }

Caveats:

There are some private KinoSearch classes for which the inside-out technique won't work (those that descend from KinoSearch::Obj::FastObj). Of course if you stick to the public API you won't encounter this problem.
Inside-out aficionados will have noted that the "cached scalar id" stratagem recommended above isn't compatible with ithreads -- but KinoSearch doesn't support ithreads anyway, so it doesn't matter.

CONSTRUCTOR

new()

Abstract constructor -- must be invoked via a subclass. Attempting to instantiate objects of class "KinoSearch::Obj" directly causes an error.

Takes no arguments; if any are supplied, an error will be reported.

DESTRUCTOR

DESTROY()

All KinoSearch classes implement a DESTROY method; if you override it in a subclass, you must call $self->SUPER::DESTROY to avoid leaking memory.