I thought about that originally, but there's only ever one object graph for the process, and as soon as you break any one edge in that graph you pretty much invalidate anything based on caching traversal results. (More accurately: it's almost always going to be cheaper to blow away and rebuild your cache than it is to determine whether or not your cache was actually affected by the graph change, particularly given the fact that object graph changes will almost always happen while the caches are still cold during application startup).

So it's not really an implementation detail, it's a promise to provide a unique token for the current state of the object graph that can be used reliably for cache invalidation.

Thus, I favour exposing a cache token as the simplest thing that could possibly work - building a mechanism for "tell me when the object graph changes" is a complex solution when the only question we need to answer is "is my cache still valid?".

So the recommended idiom with this design would be:

    new_token = abc.get_cache_token()
    if new_token != cached_token:
        cache.clear()
        cached_token = new_token
    else:
        # Do something with the cache
    # Handle a cache miss

A callback based system is actually *harder* to use, because you can't simply ask the question "Is my cache still valid?" - you have to register a callback that sets a flag, or something similar. Your lookup code ends up being:

    if cache_invalidated:
        cache.clear()
        cache_invalidated = False
    else:
        # Do something with the cache
    # Handle a cache miss

However, now you have a potential problem, because your state update (setting the flag) is decoupled from checking the flag. That makes it harder to ensure correct sequencing than is the case with a simple inline check of a cache validity token.

Choosing a solution that is harder to implement and harder to use is definitely not a good idea :)