Add identity map to ensure unique object instances

[hans]

See Oliver's good discussion of this issue at wiki:Development/UniqueInstances

Also see #187 for an example implementation of the needed getPrimaryKeyHash() method.

Although Oliver's patches were for the Propel 1.2 branch, the basic internals of Propel object hydration are basically the same in 2.0 -- and hence the implementation he suggests on the wiki is almost completely what we need.

Here is a distilled list of requirements for this task:

• Add getPrimaryKeyHash($row, $startcol) to the Peer classes.
• Add an $instances array to the Peer classes.
  • Note: I think it makes sense to keep this in the Peer classes because the Peer classes provide a natural way to categorize the classes. In particular, there could be issues with correctly categorizing instances of inherited classes. We do have to make these $instances maps public, however.
• Add logic to the retrieveByPK(), populateObjects(), and doSelectJoin*() methods to first check whether the instance was loaded before hydrating the object.
  • Note: I don't think it's worth bothering with a new version of retrieveByPKs() because that method just calls doSelect() which is going to pull objects from the identity map if they already exist.
• Finally, we should be able to simplify much of the kludgy code in Propel 1.2 that exists to prevent duplicate object instances in object trees, etc.

Also, for the implementation of getPrimaryKeyHash(), I think it makes sense to use serialize() instead of implode() for the multi-column primary key. Using serialize() is marginally slower, but it prevents problems in the case where a primary key might actually have '.' characters in it (this is not completely out of the question, as, for example, the node classes use '.' to delimit tree paths).

[hans]

Added a first-cut implementation in [409]

[hans]

Removed the change to retrieveByPK() to address ticket:290 in changeset:424. Basically, we must rely on the database for retrieveByPK() because the row may have been deleted, but is still being stored locally.

[hans]

We need to consider when items should be removed from the instance map. We probably should at least provide a method to flush the cache. This is especially relevant for those who are using Propel in non-web applications.

[oliver]

is this 2.0 or possible for 1.3 now that 1.3 contains some other substantial changes like PDO?

Myself and Tomek would be keen to contribute to getting this integrated into 1.3 if that's OK?

[david]

Good question. I'm about to try making some changes to the hydration process in order to increase performance. Could you wait until after I committed that? I'm afraid we'd create plenty of conflicts otherwise.

[hans]

I will wait until your changes are committed / stable. The actual changes to the builders were pretty trivial to enable the identity map.

[oliver]

Ok, that's fine. Let us know when you're ready.

Slightly off topic:

---

While on hydration, we noticed that the new PDO based hydration does not cast the "always string" sql values into their appropriate php types like the creole implementation used to (eg rs->getInt()).

Was this an intentional omission (it will certainly make hydration faster), or are you considering something like  http://php.net/settype?

[david]

I noticed the same while looking at the code and was just about to test that to verify it. This is a serious issue IMO. I'll write a mail to the list. Thanks for confirming this, I don't have to myself then ;)

[hans]

Added preliminary implementation of this to the 1.3 branch in changeset:481.

This implementation includes some generated Peer methods to add or remove objects from the cache:

<?php

MyPeer::addInstanceToPool($obj);
MyPeer::removeInstanceFromPool($objOrPK);
MyPeer::clearInstancePool();

I also plan to add a reload() method to the object classes to force a refresh of a particular object from the database, but that hasn't been completed at this point (and shouldn't be necessary given the pool methods above).

[hans]

In changeset:491 added object pool registration in the save() method. This now means:

<?php

$b = new Book();
// set values ...
$b->save();
$bid = $b->getId();

$b2 = BookPeer::retrieveByPK($bid);
// $b2 is same object as $b ($b2 === $b)

[hans]

Ok, I think this is pretty finished now. Probably still a couple bugs, but I think with a combination of documentation and utility methods like reload() this won't cause people problems.