[Checkins] SVN: zope.interface/trunk/src/zope/interface/adapter.py Confusion.

[Jacob Holm]

Hi Chris

Let me see if I can't clear up a bit of your confusion.

Chris McDonough wrote:
> Log message for revision 99411:
>   Confusion.
>   
> 
> Changed:
>   U   zope.interface/trunk/src/zope/interface/adapter.py
> 
> -=-
> Modified: zope.interface/trunk/src/zope/interface/adapter.py
> ===================================================================
> --- zope.interface/trunk/src/zope/interface/adapter.py	2009-04-22 23:01:33 UTC (rev 99410)
> +++ zope.interface/trunk/src/zope/interface/adapter.py	2009-04-23 01:24:17 UTC (rev 99411)
> @@ -39,6 +39,13 @@

Here is the full first comment (which was cut in half by svn):

   # {order -> {required -> {provided -> {name -> value}}}}
   # where "interfaces" is really a nested key.  So, for example:
   # for order == 0, we have:
   #   {provided -> {name -> valie}}
   # but for order == 2, we have:
   #   {r1 -> {r2 -> {provided -> {name -> valie}}}}
   #
   # XXX ^^^ what does the above comment have to do with any code
   # in this method?  and.. "interfaces is really a nested key"?
   # i don't see "interfaces" mentioned.  does it mean
   # "provided"?  what are r1 and r2?  why is the structure just
   # below this a list?  is this comment 100% bitrotten or just a
   # little? /XXX
   self._adapters = []

The comment describes the _adapters property correctly, except it should 
probably read 'required' instead of 'interfaces'.

'order' is an integer, so the outermost mapping indicated is actually a 
list. This is the list stored as self._adapters.

'required' represents the interfaces that the adapter is looked up by, 
acting like a 'nested key' as described in the comment.

'provided' is the interface provided by the adapter.

'name' is the name for named adapters, else the empty string.

'value' is the adapter factory.

What this all means is that a possible match for

    getMultiAdapter((r1, r2), provided, name=name)

can be found as:

    self._adapters[2][r1][r2][provided][name]

in the structure.




Now for the second comment:

   # Cache invalidation data.  There are really 2 kinds of registries:

   #   Invalidating registries have caches that are invalidated
   #     when they or when base registies change.  An invalidating
   #     registry can only have invalidating registries as bases.

   #   Verifying registies can't rely on getting invalidation message,
   #     so have to check the generations of base registries to determine
   #     if their cache data are current

   # ^^^ XXX what are the above comments describing? /XXX

   # Base registries:
   self.__bases__ = bases


This describes that we have registries using two different caching 
strategies.

- Invalidating registries keep track of their subregistries and 
invalidate their caches on each change. (See e.g. AdapterRegistry later 
in the same file)

- Verifying registries instead check the _generations attribute of all 
its base registries before each lookup to see if any have changed. (See 
VerifyingAdapterRegistry, also in the same file)

The actual lookups for these registries are implemented by classes 
LookupBase and VerifyingBase (which should have been named 
VerifyingLookupBase IMHO).  These are also the only bits that have an 
optional C implementation.



Hope this helps
- Jacob