/ 
KinoSearch-0.315
River stage two • 9 direct dependents • 10 total dependents
/ KinoSearch::Object::Obj

NAME

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

DEPRECATED

The KinoSearch code base has been assimilated by the Apache Lucy project. The "KinoSearch" namespace has been deprecated, but development continues under our new name at our new home: http://lucy.apache.org/

SYNOPSIS

package MyObj;
use base qw( KinoSearch::Object::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 get_foo {
    my $self = shift;
    return $foo{$$self};
}

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

DESCRIPTION

All objects in the KinoSearch:: hierarchy descend from KinoSearch::Object::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::Object::Obj and its descendants is to use the inside-out design 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:

  • 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.

  • Overridden methods must not return undef unless the API specifies that returning undef is permissible. (Failure to adhere to this rule currently results in a segfault rather than an exception.)

CONSTRUCTOR

new()

Abstract constructor -- must be invoked via a subclass. Attempting to instantiate objects of class "KinoSearch::Object::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.

ABSTRACT METHODS

to_i64()

Convert the object to a 64-bit integer.

to_f64()

Convert the object to a double precision floating point number.

load(dump)

Create an object from the output of a call to dump(). Implementations must not reference the caller.

  • dump - The output of dump().

METHODS

to_string()

Generic stringification: "ClassName@hex_mem_address".

equals(other)

Indicate whether two objects are the same. By default, compares the memory address.

  • other - Another Obj.

dump()

Return a representation of the object using only scalars, hashes, and arrays. Some implementations support JSON serialization via dump() and its companion method, load(); for others, dump() is only a debugging aid. The default simply calls to_string().

COPYRIGHT AND LICENSE

Copyright 2005-2011 Marvin Humphrey

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.