TODO list for Perl module Object::LocalVars

#--------------------------------------------------------------------------#
# Bugs to squash
#--------------------------------------------------------------------------#

#--------------------------------------------------------------------------#
# Tests to write
#--------------------------------------------------------------------------#

- test same-named class properties

#--------------------------------------------------------------------------#
# Features for release soon
#--------------------------------------------------------------------------#

- read/only attribute
- write missing documentation sections
- update benchmarks

#--------------------------------------------------------------------------#
# Potential incremental improvements
#--------------------------------------------------------------------------#

- user selectable accessor style (get_prop, set_prop)
- synonyms for :Prop (:Property :P) and :Method (:Meth :M) etc
- @array and %hash with :Prop, etc. attributes
- automethods
- naming $self as something else
- "super" like Spiffy does(?)
- mixin/trait support(?)

#--------------------------------------------------------------------------#
# Ideas involving substantial API or structural change
#--------------------------------------------------------------------------#

- switch from package globals for storing data to closures containing anonymous
  globrefs

- private subs -- have to be careful how these are used.  Don't really need to
  have Method marker because wrapper should be in place when called from some
  public interface, but this is somewhat inconsistent.  Should they have a
  wrapper that just checks that they are called privately and doesn't alias?
  Or check if the first argument is an object?  DWIM or danger here?

- thread shared objects -- use Data::Uniqid or Data::UUID or equivalent to
  generate ID and store in a registry table (See below for ideas)

#--------------------------------------------------------------------------#
# Style thoughts -- refine for POD?
#--------------------------------------------------------------------------#

May be good practice if private properties are named with an underscore, e.g.,
$_name, $_color to prevent unintentional clashes with lexicals created within
methods.  Not really necessary, but sets them apart just a bit and signals that
they are different.  (Sort of like $.name, etc. in Perl6) Or is this overkill?
If warnings are on, "our $name : Prop; my $name" will issue a warning anyway.

Write about accessor style -- using name() and set_name().  If I ever
want to use name(index) or name(key) for @array and %hash property accessors,
then I need to not use name(val) to set scalars.  set_name should return the
object, to allow chaining.  This may give a reason to *avoid* underscores, as
set__name is probably error-prone.

Mutators should be (to paraphrase Bill Clinton) "safe, legal and rare" so
maybe this doesn't matter much in the end.

#--------------------------------------------------------------------------#
# API thoughts -- refine for POD?
#--------------------------------------------------------------------------#

Too many accessors is a problem in that it breaks the OO encapsulation
paradigm.  However, accessors are common in perl to get some typo protection
(e.g. $self->{created} vs $self->{craeted} vs $self->created) and because
having perl automatically generate them is easy.  That winds up opening up the
class internals unless various protections are added to the accessors to make
them private.  With Object::LocalVars's aliasing, properties can stay private
and don't *need* an accessor.  This should be the default behavior.  Accessors
might be needed for subclasses ("protected" properties) or for certain public
access needs.  These should have to be requested.  It also means that users can
use the default (private) and then write their own custom accessors if they
need special handling, error checking, etc.

On the other hand, methods are probably usually intended to be public, so
that should be the default.  Typical Perl style is to use an underscore
to signal private functions and either document them as internal or just
not document them.  Users who call them anyway "deserve what they get" if
a future version changes things. 

This is consistent with the generally permissive Perl philosophy.  It's not
over-protective -- it give us the rope to hang ourselves with quite readily.
That said, it's easy to add the checks using properties, so we give users the
option of adding checks if they want

Summary of aliases for properties (including synonyms not yet written):

                      Aliasing   Accessor  CallerChecked ClassWide
:Property|:Prop|:P        Y          N           n/a          N
:Private|:Priv            Y          N           n/a          N
:Protected|:Prot          Y          Y           Y            N
:Public|:Pub              Y          Y           N            N         
:Class|:C                 Y          N           n/a          Y
:ClassProperty|:CProp|:CP Y          N           n/a          Y
:ClassPrivate|:CPriv      Y          N           n/a          Y
:ClassProtected|:CProt    Y          Y           Y            Y
:ClassPublic|:CPub        Y          Y           N            Y

Summary for methods:
                        CallerChecked
:Method|:Meth|:M             N
:Public|:Pub                 N
:Protected|:Prot             Y
:Private|:Priv               Y

#--------------------------------------------------------------------------#
# Thoughts on thread safety
#--------------------------------------------------------------------------#

Problem of using refaddr has been solved since 0.13 using CLONE.

Sharing objects across threads seems much trickier.  First, the package globals
holding data all need to be shared.  Next, access has to be coordinated could
be done with semaphors in the wrapper or locking the object tracker hash, but
that blocks everything on that object until the method exits.  Accessors can
lock the target before reading/writing the same way.  Still ugly if accessing
an array or hash-ref -- the method will have to lock that, too, I think, or
will have to get/store.  Alias of $self should still be OK, as that's just
aliasing a subroutine argument within the same thread.

Smart thing to do is have Object::LocalVars automatically install the right
versions of locking/sharing subs or otherwise based on whether 
%INC{"threads/shared.pm"} is defined.

Other potential snags:

- New objects created in one thread will still have data available in other
  threads due to shared data storage hashes, but won't be easily accessable.
  Would need to have a way to have a thread pass or return an object UUID to
  allow another thread to know what to manipulate.

- Object destruction also becomes an issue -- can't destroy data when the
  reference count goes to zero because the object might exists in the other
  thread.  Have to disable DESTROY and have users manually destroy UUIDs when
  they are done with them, or have to keep object counts during CLONE, etc.

