xcb: Add a short comment to the Picture cache

When we create a temporary cairo_xcb_picture_t, we want to be able to
reuse it, but we don't want the Picture to be alive forever to eat up
resources when it is not being used anymore.

When a surface pattern is about to be used for compositing, if it has
a cairo_xcb_picture_t snapshot, the latter is just reused. Otherwise a
new cairo_xcb_picture_t with the same content is created and attached
as a snapshot to the surface.

To keep the resource usage bounded we keep a per-screen cache of
cairo_xcb_picture_t. When the cache is full, a random entry is evicted
and we detach this snapshot from the surface that it is a snapshot
for. It will be immediately destroyed if nothing else holds a
reference to it. Otherwise it will be charged against the holder of
the reference, so it won't count anymore in the resources occupied by
the cache elements. This makes sure that the cached surface isn't
kept alive indefinitely because of caching.

Based on a patch by Uli Schlachter.

1 files changed, 4 insertions, 0 deletions

diff --git a/src/cairo-xcb-screen.c b/src/cairo-xcb-screen.c
index c80bf2d9a..5e94d49b1 100644
--- a/src/cairo-xcb-screen.c
+++ b/src/cairo-xcb-screen.c
@@ -116,6 +116,10 @@ _surface_cache_entry_destroy (void *closure)
 {
     struct pattern_cache_entry *entry = closure;
 
+    /* Destroy all the references to the surfaces that were generated
+     * because of the caching. This means that the cache is giving up
+     * the resources held by that surface. They are now considered as
+     * owned by whatever holds a reference to the surface. */
     if (entry->picture->snapshot_of != NULL)
 	_cairo_surface_detach_snapshot (entry->picture);
     cairo_surface_destroy (entry->picture);