Mailing List Archive

Author: creamyg
Date: 2008-08-30 11:55:58 -0700 (Sat, 30 Aug 2008)
New Revision: 3803

Modified:
trunk/perl/lib/KinoSearch/Obj.pm
Log:
Expose KinoSearch::Obj as a part of the public Perl API. Document subclassing
strategy.


Modified: trunk/perl/lib/KinoSearch/Obj.pm
===================================================================
--- trunk/perl/lib/KinoSearch/Obj.pm 2008-08-30 18:43:41 UTC (rev 3802)
+++ trunk/perl/lib/KinoSearch/Obj.pm 2008-08-30 18:55:58 UTC (rev 3803)
@@ -136,9 +136,103 @@
},
}

-__COPYRIGHT__
+__POD__

-Copyright 2005-2008 Marvin Humphrey
+=head1 NAME

-This program is free software; you can redistribute it and/or modify
-under the same terms as Perl itself.
+KinoSearch::Obj - Base class for all KinoSearch objects.
+
+=head1 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;
+ }
+
+=head1 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.
+
+=head2 Subclassing
+
+The recommended way to subclass KinoSearch::Obj and its descendants is to use
+the inside-out pattern. (See L<Class::InsideOut> for an introduction to
+inside-out techniques.)
+
+Since the blessed scalar stores a C pointer value which is unique per-object,
+C<$$self> can be used as an inside-out ID.
+
+ # Accessor for 'foo' member variable.
+ sub get_foo {
+ my $self = shift;
+ return $foo{$$self};
+ }
+
+
+Caveats:
+
+=over
+
+=item *
+
+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.
+
+=item *
+
+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.
+
+=back
+
+=head1 CONSTRUCTOR
+
+=head2 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.
+
+=head1 DESTRUCTOR
+
+=head2 DESTROY()
+
+All KinoSearch classes implement a DESTROY method; if you override it in a
+subclass, you must call C<< $self->SUPER::DESTROY >> to avoid leaking memory.
+
+=head1 METHODS
+
+=head2 to_string()
+
+Return a string representation of the object.
+
+=head1 COPYRIGHT
+
+Copyright 2006-2008 Marvin Humphrey
+
+=head1 LICENSE, DISCLAIMER, BUGS, etc.
+
+See L<KinoSearch> version 0.20.
+
+=cut
+


_______________________________________________
kinosearch-commits mailing list
kinosearch-commits@rectangular.com
http://www.rectangular.com/mailman/listinfo/kinosearch-commits