'. '


From APIDesign

Jump to: navigation, search

Chapter 11 talks about Runtime_Aspects_of_APIs and includes a paragraph about the importance of references from an API point of view:

If a reference to your object (like listener) is for example changed from normal reference (in first version) to WeakReference (in subsequent version), it may be an incompatible API change. Suddenly client listeners may disappear from memory. In spite they would previously receive their notifications.

Keep Your References!

This happened to me few times with Lookup.Result - its listeners are supposed to keep hard-reference to the result instance otherwise it may disappear. Sometimes the users forget to do so and then they get broken code. Well, half-broken code. Why half-broken?

However, the results were partially cached and as such it was enough if only one user of the same result kept the reference. This resulted in funny situations when some PHP functionality in NetBeans worked correctly only if C/C++ support was also installed. Moreover problems of this kind are hard to debug (especially few beginners): when you debug your application everything works initially. Only after few full garbage collector cycles the listener actually gets garbage collected - may seem a bit mysterious for those who use debugger blindly.

Caching May Change Any API

For NetBeans 7.4 I improved the Lookup result caching. Now I do my best to share instances of results that already exist. The result? Three or four new and important memory leaks! As suddenly the results started to be long living object and kept all its listeners in memory almost indefinitely.

References (and their types) from an API instances to client objects are important part of the API.

Apologies to those with code broken by my lookup result caching change. I think I had to do it to make different kinds of lookup consistent. Now the caching is part of lookup TCK and all instances now must behave the same - at least the amoeba of the lookup API now has stiffer edges.

Personal tools