evolution/e-util/e-photo-cache.c

/*
 * e-photo-cache.c
 *
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program; if not, see <http://www.gnu.org/licenses/>.
 *
 */

/**
 * SECTION: e-photo-cache
 * @include: e-util/e-util.h
 * @short_description: Search for photos by email address
 *
 * #EPhotoCache finds photos associated with an email address.
 *
 * A limited internal cache is employed to speed up frequently searched
 * email addresses.  The exact caching semantics are private and subject
 * to change.
 **/

#include "e-photo-cache.h"

#include <string.h>
#include <libebackend/libebackend.h>

#include <e-util/e-data-capture.h>

#define E_PHOTO_CACHE_GET_PRIVATE(obj) \
	(G_TYPE_INSTANCE_GET_PRIVATE \
	((obj), E_TYPE_PHOTO_CACHE, EPhotoCachePrivate))

/* How long (in seconds) to hold out for a hit from the highest
 * priority photo source, after which we settle for what we have. */
#define ASYNC_TIMEOUT_SECONDS 3.0

/* How many email addresses we track at once, regardless of whether
 * the email address has a photo.  As new cache entries are added, we
 * discard the least recently accessed entries to keep the cache size
 * within the limit. */
#define MAX_CACHE_SIZE 20

#define ERROR_IS_CANCELLED(error) \
	(g_error_matches ((error), G_IO_ERROR, G_IO_ERROR_CANCELLED))

typedef struct _AsyncContext AsyncContext;
typedef struct _AsyncSubtask AsyncSubtask;
typedef struct _DataCaptureClosure DataCaptureClosure;
typedef struct _PhotoData PhotoData;

struct _EPhotoCachePrivate {
	EClientCache *client_cache;
	GMainContext *main_context;

	GHashTable *photo_ht;
	GQueue photo_ht_keys;
	GMutex photo_ht_lock;

	GHashTable *sources_ht;
	GMutex sources_ht_lock;
};

struct _AsyncContext {
	GMutex lock;
	GTimer *timer;
	GHashTable *subtasks;
	GQueue results;
	GInputStream *stream;
	GConverter *data_capture;

	GCancellable *cancellable;
	gulong cancelled_handler_id;
};

struct _AsyncSubtask {
	volatile gint ref_count;
	EPhotoSource *photo_source;
	GSimpleAsyncResult *simple;
	GCancellable *cancellable;
	GInputStream *stream;
	gint priority;
	GError *error;
};

struct _DataCaptureClosure {
	GWeakRef photo_cache;
	gchar *email_address;
};

struct _PhotoData {
	volatile gint ref_count;
	GMutex lock;
	GBytes *bytes;
};

enum {
	PROP_0,
	PROP_CLIENT_CACHE
};

/* Forward Declarations */
static void	async_context_cancel_subtasks	(AsyncContext *async_context);

G_DEFINE_TYPE_WITH_CODE (
	EPhotoCache,
	e_photo_cache,
	G_TYPE_OBJECT,
	G_IMPLEMENT_INTERFACE (
		E_TYPE_EXTENSIBLE, NULL))

static AsyncSubtask *
async_subtask_new (EPhotoSource *photo_source,
                   GSimpleAsyncResult *simple)
{
	AsyncSubtask *async_subtask;

	async_subtask = g_slice_new0 (AsyncSubtask);
	async_subtask->ref_count = 1;
	async_subtask->photo_source = g_object_ref (photo_source);
	async_subtask->simple = g_object_ref (simple);
	async_subtask->cancellable = g_cancellable_new ();
	async_subtask->priority = G_PRIORITY_DEFAULT;

	return async_subtask;
}

static AsyncSubtask *
async_subtask_ref (AsyncSubtask *async_subtask)
{
	g_return_val_if_fail (async_subtask != NULL, NULL);
	g_return_val_if_fail (async_subtask->ref_count > 0, NULL);

	g_atomic_int_inc (&async_subtask->ref_count);

	return async_subtask;
}

static void
async_subtask_unref (AsyncSubtask *async_subtask)
{
	g_return_if_fail (async_subtask != NULL);
	g_return_if_fail (async_subtask->ref_count > 0);

	if (g_atomic_int_dec_and_test (&async_subtask->ref_count)) {

		/* Ignore cancellations. */
		if (ERROR_IS_CANCELLED (async_subtask->error))
			g_clear_error (&async_subtask->error);

		/* Leave a breadcrumb on the console
		 * about unpropagated subtask errors. */
		if (async_subtask->error != NULL) {
			g_warning (
				"%s: Unpropagated error in %s subtask: %s",
				__FILE__,
				G_OBJECT_TYPE_NAME (
				async_subtask->photo_source),
				async_subtask->error->message);
			g_error_free (async_subtask->error);
		}

		g_clear_object (&async_subtask->photo_source);
		g_clear_object (&async_subtask->simple);
		g_clear_object (&async_subtask->cancellable);
		g_clear_object (&async_subtask->stream);

		g_slice_free (AsyncSubtask, async_subtask);
	}
}

static gboolean
async_subtask_cancel_idle_cb (gpointer user_data)
{
	AsyncSubtask *async_subtask = user_data;

	g_cancellable_cancel (async_subtask->cancellable);

	return FALSE;
}

static gint
async_subtask_compare (gconstpointer a,
                       gconstpointer b)
{
	const AsyncSubtask *subtask_a = a;
	const AsyncSubtask *subtask_b = b;

	/* Without error is always less than with error. */

	if (subtask_a->error != NULL && subtask_b->error != NULL)
		return 0;

	if (subtask_a->error == NULL && subtask_b->error != NULL)
		return -1;

	if (subtask_a->error != NULL && subtask_b->error == NULL)
		return 1;

	if (subtask_a->priority == subtask_b->priority)
		return 0;

	return (subtask_a->priority < subtask_b->priority) ? -1 : 1;
}

static void
async_subtask_complete (AsyncSubtask *async_subtask)
{
	GSimpleAsyncResult *simple;
	AsyncContext *async_context;
	gboolean cancel_subtasks = FALSE;
	gdouble seconds_elapsed;

	simple = async_subtask->simple;
	async_context = g_simple_async_result_get_op_res_gpointer (simple);

	g_mutex_lock (&async_context->lock);

	seconds_elapsed = g_timer_elapsed (async_context->timer, NULL);

	/* Discard successfully completed subtasks with no match found.
	 * Keep failed subtasks around so we have a GError to propagate
	 * if we need one, but those go on the end of the queue. */

	if (async_subtask->stream != NULL) {
		g_queue_insert_sorted (
			&async_context->results,
			async_subtask_ref (async_subtask),
			(GCompareDataFunc) async_subtask_compare,
			NULL);

		/* If enough seconds have elapsed, just take the highest
		 * priority input stream we have.  Cancel the unfinished
		 * subtasks and let them complete with an error. */
		if (seconds_elapsed > ASYNC_TIMEOUT_SECONDS)
			cancel_subtasks = TRUE;

	} else if (async_subtask->error != NULL) {
		g_queue_push_tail (
			&async_context->results,
			async_subtask_ref (async_subtask));
	}

	g_hash_table_remove (async_context->subtasks, async_subtask);

	if (g_hash_table_size (async_context->subtasks) > 0) {
		/* Let the remaining subtasks finish. */
		goto exit;
	}

	/* The queue should be ordered now such that subtasks
	 * with input streams are before subtasks with errors.
	 * So just evaluate the first subtask on the queue. */

	async_subtask = g_queue_pop_head (&async_context->results);

	if (async_subtask != NULL) {
		if (async_subtask->stream != NULL) {
			async_context->stream =
				g_converter_input_stream_new (
					async_subtask->stream,
					async_context->data_capture);
		}

		if (async_subtask->error != NULL) {
			g_simple_async_result_take_error (
				simple, async_subtask->error);
			async_subtask->error = NULL;
		}

		async_subtask_unref (async_subtask);
	}

	g_simple_async_result_complete_in_idle (simple);

exit:
	g_mutex_unlock (&async_context->lock);

	if (cancel_subtasks) {
		/* Call this after the mutex is unlocked. */
		async_context_cancel_subtasks (async_context);
	}
}

static void
async_context_cancelled_cb (GCancellable *cancellable,
                            AsyncContext *async_context)
{
	async_context_cancel_subtasks (async_context);
}

static AsyncContext *
async_context_new (EDataCapture *data_capture,
                   GCancellable *cancellable)
{
	AsyncContext *async_context;

	async_context = g_slice_new0 (AsyncContext);
	g_mutex_init (&async_context->lock);
	async_context->timer = g_timer_new ();

	async_context->subtasks = g_hash_table_new_full (
		(GHashFunc) g_direct_hash,
		(GEqualFunc) g_direct_equal,
		(GDestroyNotify) async_subtask_unref,
		(GDestroyNotify) NULL);

	async_context->data_capture = g_object_ref (data_capture);

	if (G_IS_CANCELLABLE (cancellable)) {
		gulong handler_id;

		async_context->cancellable = g_object_ref (cancellable);

		handler_id = g_cancellable_connect (
			async_context->cancellable,
			G_CALLBACK (async_context_cancelled_cb),
			async_context,
			(GDestroyNotify) NULL);
		async_context->cancelled_handler_id = handler_id;
	}

	return async_context;
}

static void
async_context_free (AsyncContext *async_context)
{
	/* Do this first so the callback won't fire
	 * while we're dismantling the AsyncContext. */
	if (async_context->cancelled_handler_id > 0)
		g_cancellable_disconnect (
			async_context->cancellable,
			async_context->cancelled_handler_id);

	g_mutex_clear (&async_context->lock);
	g_timer_destroy (async_context->timer);

	g_hash_table_destroy (async_context->subtasks);

	g_clear_object (&async_context->stream);
	g_clear_object (&async_context->data_capture);
	g_clear_object (&async_context->cancellable);

	g_slice_free (AsyncContext, async_context);
}

static void
async_context_cancel_subtasks (AsyncContext *async_context)
{
	GMainContext *main_context;
	GList *list, *link;

	main_context = g_main_context_ref_thread_default ();

	g_mutex_lock (&async_context->lock);

	list = g_hash_table_get_keys (async_context->subtasks);

	/* XXX Cancel subtasks from idle callbacks to make sure we don't
	 *     finalize the GSimpleAsyncResult during a "cancelled" signal
	 *     emission from the main task's GCancellable.  That will make
	 *     g_cancellable_disconnect() in async_context_free() deadlock. */
	for (link = list; link != NULL; link = g_list_next (link)) {
		AsyncSubtask *async_subtask = link->data;
		GSource *idle_source;

		idle_source = g_idle_source_new ();
		g_source_set_priority (idle_source, G_PRIORITY_HIGH_IDLE);
		g_source_set_callback (
			idle_source,
			async_subtask_cancel_idle_cb,
			async_subtask_ref (async_subtask),
			(GDestroyNotify) async_subtask_unref);
		g_source_attach (idle_source, main_context);
		g_source_unref (idle_source);
	}

	g_list_free (list);

	g_mutex_unlock (&async_context->lock);

	g_main_context_unref (main_context);
}

static DataCaptureClosure *
data_capture_closure_new (EPhotoCache *photo_cache,
                          const gchar *email_address)
{
	DataCaptureClosure *closure;

	closure = g_slice_new0 (DataCaptureClosure);
	g_weak_ref_set (&closure->photo_cache, photo_cache);
	closure->email_address = g_strdup (email_address);

	return closure;
}

static void
data_capture_closure_free (DataCaptureClosure *closure)
{
	g_weak_ref_set (&closure->photo_cache, NULL);
	g_free (closure->email_address);

	g_slice_free (DataCaptureClosure, closure);
}

static PhotoData *
photo_data_new (GBytes *bytes)
{
	PhotoData *photo_data;

	photo_data = g_slice_new0 (PhotoData);
	photo_data->ref_count = 1;
	g_mutex_init (&photo_data->lock);

	if (bytes != NULL)
		photo_data->bytes = g_bytes_ref (bytes);

	return photo_data;
}

static PhotoData *
photo_data_ref (PhotoData *photo_data)
{
	g_return_val_if_fail (photo_data != NULL, NULL);
	g_return_val_if_fail (photo_data->ref_count > 0, NULL);

	g_atomic_int_inc (&photo_data->ref_count);

	return photo_data;
}

static void
photo_data_unref (PhotoData *photo_data)
{
	g_return_if_fail (photo_data != NULL);
	g_return_if_fail (photo_data->ref_count > 0);

	if (g_atomic_int_dec_and_test (&photo_data->ref_count)) {
		g_mutex_clear (&photo_data->lock);
		if (photo_data->bytes != NULL)
			g_bytes_unref (photo_data->bytes);
		g_slice_free (PhotoData, photo_data);
	}
}

static GBytes *
photo_data_ref_bytes (PhotoData *photo_data)
{
	GBytes *bytes = NULL;

	g_mutex_lock (&photo_data->lock);

	if (photo_data->bytes != NULL)
		bytes = g_bytes_ref (photo_data->bytes);

	g_mutex_unlock (&photo_data->lock);

	return bytes;
}

static void
photo_data_set_bytes (PhotoData *photo_data,
                      GBytes *bytes)
{
	g_mutex_lock (&photo_data->lock);

	if (photo_data->bytes != NULL) {
		g_bytes_unref (photo_data->bytes);
		photo_data->bytes = NULL;
	}

	if (bytes != NULL)
		photo_data->bytes = g_bytes_ref (bytes);

	g_mutex_unlock (&photo_data->lock);
}

static gchar *
photo_ht_normalize_key (const gchar *email_address)
{
	gchar *lowercase_email_address;
	gchar *collation_key;

	lowercase_email_address = g_utf8_strdown (email_address, -1);
	collation_key = g_utf8_collate_key (lowercase_email_address, -1);
	g_free (lowercase_email_address);

	return collation_key;
}

static void
photo_ht_insert (EPhotoCache *photo_cache,
                 const gchar *email_address,
                 GBytes *bytes)
{
	GHashTable *photo_ht;
	GQueue *photo_ht_keys;
	PhotoData *photo_data;
	gchar *key;

	g_return_if_fail (email_address != NULL);

	photo_ht = photo_cache->priv->photo_ht;
	photo_ht_keys = &photo_cache->priv->photo_ht_keys;

	key = photo_ht_normalize_key (email_address);

	g_mutex_lock (&photo_cache->priv->photo_ht_lock);

	photo_data = g_hash_table_lookup (photo_ht, key);

	if (photo_data != NULL) {
		GList *link;

		/* Replace the old photo data if we have new photo
		 * data, otherwise leave the old photo data alone. */
		if (bytes != NULL)
			photo_data_set_bytes (photo_data, bytes);

		/* Move the key to the head of the MRU queue. */
		link = g_queue_find_custom (
			photo_ht_keys, key,
			(GCompareFunc) strcmp);
		if (link != NULL) {
			g_queue_unlink (photo_ht_keys, link);
			g_queue_push_head_link (photo_ht_keys, link);
		}
	} else {
		photo_data = photo_data_new (bytes);

		g_hash_table_insert (
			photo_ht, g_strdup (key),
			photo_data_ref (photo_data));

		/* Push the key to the head of the MRU queue. */
		g_queue_push_head (photo_ht_keys, g_strdup (key));

		/* Trim the cache if necessary. */
		while (g_queue_get_length (photo_ht_keys) > MAX_CACHE_SIZE) {
			gchar *oldest_key;

			oldest_key = g_queue_pop_tail (photo_ht_keys);
			g_hash_table_remove (photo_ht, oldest_key);
			g_free (oldest_key);
		}

		photo_data_unref (photo_data);
	}

	/* Hash table and queue sizes should be equal at all times. */
	g_warn_if_fail (
		g_hash_table_size (photo_ht) ==
		g_queue_get_length (photo_ht_keys));

	g_mutex_unlock (&photo_cache->priv->photo_ht_lock);

	g_free (key);
}

static gboolean
photo_ht_lookup (EPhotoCache *photo_cache,
                 const gchar *email_address,
                 GInputStream **out_stream)
{
	GHashTable *photo_ht;
	PhotoData *photo_data;
	gboolean found = FALSE;
	gchar *key;

	g_return_val_if_fail (email_address != NULL, FALSE);
	g_return_val_if_fail (out_stream != NULL, FALSE);

	photo_ht = photo_cache->priv->photo_ht;

	key = photo_ht_normalize_key (email_address);

	g_mutex_lock (&photo_cache->priv->photo_ht_lock);

	photo_data = g_hash_table_lookup (photo_ht, key);

	if (photo_data != NULL) {
		GBytes *bytes;

		bytes = photo_data_ref_bytes (photo_data);
		if (bytes != NULL) {
			*out_stream =
				g_memory_input_stream_new_from_bytes (bytes);
			g_bytes_unref (bytes);
		} else {
			*out_stream = NULL;
		}
		found = TRUE;
	}

	g_mutex_unlock (&photo_cache->priv->photo_ht_lock);

	g_free (key);

	return found;
}

static gboolean
photo_ht_remove (EPhotoCache *photo_cache,
                 const gchar *email_address)
{
	GHashTable *photo_ht;
	GQueue *photo_ht_keys;
	gchar *key;
	gboolean removed = FALSE;

	g_return_val_if_fail (email_address != NULL, FALSE);

	photo_ht = photo_cache->priv->photo_ht;
	photo_ht_keys = &photo_cache->priv->photo_ht_keys;

	key = photo_ht_normalize_key (email_address);

	g_mutex_lock (&photo_cache->priv->photo_ht_lock);

	if (g_hash_table_remove (photo_ht, key)) {
		GList *link;

		link = g_queue_find_custom (
			photo_ht_keys, key,
			(GCompareFunc) strcmp);
		if (link != NULL) {
			g_free (link->data);
			g_queue_delete_link (photo_ht_keys, link);
			removed = TRUE;
		}
	}

	/* Hash table and queue sizes should be equal at all times. */
	g_warn_if_fail (
		g_hash_table_size (photo_ht) ==
		g_queue_get_length (photo_ht_keys));

	g_mutex_unlock (&photo_cache->priv->photo_ht_lock);

	g_free (key);

	return removed;
}

static void
photo_ht_remove_all (EPhotoCache *photo_cache)
{
	GHashTable *photo_ht;
	GQueue *photo_ht_keys;

	photo_ht = photo_cache->priv->photo_ht;
	photo_ht_keys = &photo_cache->priv->photo_ht_keys;

	g_mutex_lock (&photo_cache->priv->photo_ht_lock);

	g_hash_table_remove_all (photo_ht);

	while (!g_queue_is_empty (photo_ht_keys))
		g_free (g_queue_pop_head (photo_ht_keys));

	g_mutex_unlock (&photo_cache->priv->photo_ht_lock);
}

static void
photo_cache_data_captured_cb (EDataCapture *data_capture,
                              GBytes *bytes,
                              DataCaptureClosure *closure)
{
	EPhotoCache *photo_cache;

	photo_cache = g_weak_ref_get (&closure->photo_cache);

	if (photo_cache != NULL) {
		e_photo_cache_add_photo (
			photo_cache, closure->email_address, bytes);
		g_object_unref (photo_cache);
	}
}

static void
photo_cache_async_subtask_done_cb (GObject *source_object,
                                   GAsyncResult *result,
                                   gpointer user_data)
{
	AsyncSubtask *async_subtask = user_data;

	e_photo_source_get_photo_finish (
		E_PHOTO_SOURCE (source_object),
		result,
		&async_subtask->stream,
		&async_subtask->priority,
		&async_subtask->error);

	async_subtask_complete (async_subtask);
	async_subtask_unref (async_subtask);
}

static void
photo_cache_set_client_cache (EPhotoCache *photo_cache,
                              EClientCache *client_cache)
{
	g_return_if_fail (E_IS_CLIENT_CACHE (client_cache));
	g_return_if_fail (photo_cache->priv->client_cache == NULL);

	photo_cache->priv->client_cache = g_object_ref (client_cache);
}

static void
photo_cache_set_property (GObject *object,
                          guint property_id,
                          const GValue *value,
                          GParamSpec *pspec)
{
	switch (property_id) {
		case PROP_CLIENT_CACHE:
			photo_cache_set_client_cache (
				E_PHOTO_CACHE (object),
				g_value_get_object (value));
			return;
	}

	G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
}

static void
photo_cache_get_property (GObject *object,
                          guint property_id,
                          GValue *value,
                          GParamSpec *pspec)
{
	switch (property_id) {
		case PROP_CLIENT_CACHE:
			g_value_take_object (
				value,
				e_photo_cache_ref_client_cache (
				E_PHOTO_CACHE (object)));
			return;
	}

	G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
}

static void
photo_cache_dispose (GObject *object)
{
	EPhotoCachePrivate *priv;

	priv = E_PHOTO_CACHE_GET_PRIVATE (object);

	g_clear_object (&priv->client_cache);

	photo_ht_remove_all (E_PHOTO_CACHE (object));

	/* Chain up to parent's dispose() method. */
	G_OBJECT_CLASS (e_photo_cache_parent_class)->dispose (object);
}

static void
photo_cache_finalize (GObject *object)
{
	EPhotoCachePrivate *priv;

	priv = E_PHOTO_CACHE_GET_PRIVATE (object);

	g_main_context_unref (priv->main_context);

	g_hash_table_destroy (priv->photo_ht);
	g_hash_table_destroy (priv->sources_ht);

	g_mutex_clear (&priv->photo_ht_lock);
	g_mutex_clear (&priv->sources_ht_lock);

	/* Chain up to parent's finalize() method. */
	G_OBJECT_CLASS (e_photo_cache_parent_class)->finalize (object);
}

static void
photo_cache_constructed (GObject *object)
{
	/* Chain up to parent's constructed() method. */
	G_OBJECT_CLASS (e_photo_cache_parent_class)->constructed (object);

	e_extensible_load_extensions (E_EXTENSIBLE (object));
}

static void
e_photo_cache_class_init (EPhotoCacheClass *class)
{
	GObjectClass *object_class;

	g_type_class_add_private (class, sizeof (EPhotoCachePrivate));

	object_class = G_OBJECT_CLASS (class);
	object_class->set_property = photo_cache_set_property;
	object_class->get_property = photo_cache_get_property;
	object_class->dispose = photo_cache_dispose;
	object_class->finalize = photo_cache_finalize;
	object_class->constructed = photo_cache_constructed;

	/**
	 * EPhotoCache:client-cache:
	 *
	 * Cache of shared #EClient instances.
	 **/
	g_object_class_install_property (
		object_class,
		PROP_CLIENT_CACHE,
		g_param_spec_object (
			"client-cache",
			"Client Cache",
			"Cache of shared EClient instances",
			E_TYPE_CLIENT_CACHE,
			G_PARAM_READWRITE |
			G_PARAM_CONSTRUCT_ONLY |
			G_PARAM_STATIC_STRINGS));
}

static void
e_photo_cache_init (EPhotoCache *photo_cache)
{
	GHashTable *photo_ht;
	GHashTable *sources_ht;

	photo_ht = g_hash_table_new_full (
		(GHashFunc) g_str_hash,
		(GEqualFunc) g_str_equal,
		(GDestroyNotify) g_free,
		(GDestroyNotify) photo_data_unref);

	sources_ht = g_hash_table_new_full (
		(GHashFunc) g_direct_hash,
		(GEqualFunc) g_direct_equal,
		(GDestroyNotify) g_object_unref,
		(GDestroyNotify) NULL);

	photo_cache->priv = E_PHOTO_CACHE_GET_PRIVATE (photo_cache);
	photo_cache->priv->main_context = g_main_context_ref_thread_default ();
	photo_cache->priv->photo_ht = photo_ht;
	photo_cache->priv->sources_ht = sources_ht;

	g_mutex_init (&photo_cache->priv->photo_ht_lock);
	g_mutex_init (&photo_cache->priv->sources_ht_lock);
}

/**
 * e_photo_cache_new:
 * @client_cache: an #EClientCache
 *
 * Creates a new #EPhotoCache instance.
 *
 * Returns: an #EPhotoCache
 **/
EPhotoCache *
e_photo_cache_new (EClientCache *client_cache)
{
	g_return_val_if_fail (E_IS_CLIENT_CACHE (client_cache), NULL);

	return g_object_new (
		E_TYPE_PHOTO_CACHE,
		"client-cache", client_cache, NULL);
}

/**
 * e_photo_cache_ref_client_cache:
 * @photo_cache: an #EPhotoCache
 *
 * Returns the #EClientCache passed to e_photo_cache_new().
 *
 * The returned #EClientCache is referenced for thread-safety and must be
 * unreferenced with g_object_unref() when finished with it.
 *
 * Returns: an #EClientCache
 **/
EClientCache *
e_photo_cache_ref_client_cache (EPhotoCache *photo_cache)
{
	g_return_val_if_fail (E_IS_PHOTO_CACHE (photo_cache), NULL);

	return g_object_ref (photo_cache->priv->client_cache);
}

/**
 * e_photo_cache_add_photo_source:
 * @photo_cache: an #EPhotoCache
 * @photo_source: an #EPhotoSource
 *
 * Adds @photo_source as a potential source of photos.
 **/
void
e_photo_cache_add_photo_source (EPhotoCache *photo_cache,
                                EPhotoSource *photo_source)
{
	GHashTable *sources_ht;

	g_return_if_fail (E_IS_PHOTO_CACHE (photo_cache));
	g_return_if_fail (E_IS_PHOTO_SOURCE (photo_source));

	sources_ht = photo_cache->priv->sources_ht;

	g_mutex_lock (&photo_cache->priv->sources_ht_lock);

	g_hash_table_add (sources_ht, g_object_ref (photo_source));

	g_mutex_unlock (&photo_cache->priv->sources_ht_lock);
}

/**
 * e_photo_cache_list_photo_sources:
 * @photo_cache: an #EPhotoCache
 *
 * Returns a list of photo sources for @photo_cache.
 *
 * The sources returned in the list are referenced for thread-safety.
 * They must each be unreferenced with g_object_unref() when finished
 * with them.  Free the returned list itself with g_list_free().
 *
 * An easy way to free the list property in one step is as follows:
 *
 * |[
 *   g_list_free_full (list, g_object_unref);
 * ]|
 *
 * Returns: a sorted list of photo sources
 **/
GList *
e_photo_cache_list_photo_sources (EPhotoCache *photo_cache)
{
	GHashTable *sources_ht;
	GList *list;

	g_return_val_if_fail (E_IS_PHOTO_CACHE (photo_cache), NULL);

	sources_ht = photo_cache->priv->sources_ht;

	g_mutex_lock (&photo_cache->priv->sources_ht_lock);

	list = g_hash_table_get_keys (sources_ht);
	g_list_foreach (list, (GFunc) g_object_ref, NULL);

	g_mutex_unlock (&photo_cache->priv->sources_ht_lock);

	return list;
}

/**
 * e_photo_cache_remove_photo_source:
 * @photo_cache: an #EPhotoCache
 * @photo_source: an #EPhotoSource
 *
 * Removes @photo_source as a potential source of photos.
 *
 * Returns: %TRUE if @photo_source was found and removed, %FALSE if not
 **/
gboolean
e_photo_cache_remove_photo_source (EPhotoCache *photo_cache,
                                   EPhotoSource *photo_source)
{
	GHashTable *sources_ht;
	gboolean removed;

	g_return_val_if_fail (E_IS_PHOTO_CACHE (photo_cache), FALSE);
	g_return_val_if_fail (E_IS_PHOTO_SOURCE (photo_source), FALSE);

	sources_ht = photo_cache->priv->sources_ht;

	g_mutex_lock (&photo_cache->priv->sources_ht_lock);

	removed = g_hash_table_remove (sources_ht, photo_source);

	g_mutex_unlock (&photo_cache->priv->sources_ht_lock);

	return removed;
}

/**
 * e_photo_cache_add_photo:
 * @photo_cache: an #EPhotoCache
 * @email_address: an email address
 * @bytes: a #GBytes containing photo data, or %NULL
 *
 * Adds a cache entry for @email_address, such that subsequent photo requests
 * for @email_address will yield a #GMemoryInputStream loaded with @bytes
 * without consulting available photo sources.
 *
 * The @bytes argument can also be %NULL to indicate no photo is available for
 * @email_address.  Subsequent photo requests for @email_address will yield no
 * input stream.
 *
 * The entry may be removed without notice however, subject to @photo_cache's
 * internal caching policy.
 **/
void
e_photo_cache_add_photo (EPhotoCache *photo_cache,
                         const gchar *email_address,
                         GBytes *bytes)
{
	g_return_if_fail (E_IS_PHOTO_CACHE (photo_cache));
	g_return_if_fail (email_address != NULL);

	photo_ht_insert (photo_cache, email_address, bytes);
}

/**
 * e_photo_cache_remove_photo:
 * @photo_cache: an #EPhotoCache
 * @email_address: an email address
 *
 * Removes the cache entry for @email_address, if such an entry exists.
 *
 * Returns: %TRUE if a cache entry was found and removed
 **/
gboolean
e_photo_cache_remove_photo (EPhotoCache *photo_cache,
                            const gchar *email_address)
{
	g_return_val_if_fail (E_IS_PHOTO_CACHE (photo_cache), FALSE);
	g_return_val_if_fail (email_address != NULL, FALSE);

	return photo_ht_remove (photo_cache, email_address);
}

/**
 * e_photo_cache_get_photo_sync:
 * @photo_cache: an #EPhotoCache
 * @email_address: an email address
 * @cancellable: optional #GCancellable object, or %NULL
 * @out_stream: return location for a #GInputStream, or %NULL
 * @error: return location for a #GError, or %NULL
 *
 * Searches available photo sources for a photo associated with
 * @email_address.
 *
 * If a match is found, a #GInputStream from which to read image data is
 * returned through the @out_stream return location.  If no match is found,
 * the @out_stream return location is set to %NULL.
 *
 * The return value indicates whether the search completed successfully,
 * not whether a match was found.  If an error occurs, the function will
 * set @error and return %FALSE.
 *
 * Returns: whether the search completed successfully
 **/
gboolean
e_photo_cache_get_photo_sync (EPhotoCache *photo_cache,
                              const gchar *email_address,
                              GCancellable *cancellable,
                              GInputStream **out_stream,
                              GError **error)
{
	EAsyncClosure *closure;
	GAsyncResult *result;
	gboolean success;

	closure = e_async_closure_new ();

	e_photo_cache_get_photo (
		photo_cache, email_address, cancellable,
		e_async_closure_callback, closure);

	result = e_async_closure_wait (closure);

	success = e_photo_cache_get_photo_finish (
		photo_cache, result, out_stream, error);

	e_async_closure_free (closure);

	return success;
}

/**
 * e_photo_cache_get_photo:
 * @photo_cache: an #EPhotoCache
 * @email_address: an email address
 * @cancellable: optional #GCancellable object, or %NULL
 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
 * @user_data: data to pass to the callback function
 *
 * Asynchronously searches available photo sources for a photo associated
 * with @email_address.
 *
 * When the operation is finished, @callback will be called.  You can then
 * call e_photo_cache_get_photo_finish() to get the result of the operation.
 **/
void
e_photo_cache_get_photo (EPhotoCache *photo_cache,
                         const gchar *email_address,
                         GCancellable *cancellable,
                         GAsyncReadyCallback callback,
                         gpointer user_data)
{
	GSimpleAsyncResult *simple;
	AsyncContext *async_context;
	EDataCapture *data_capture;
	GInputStream *stream = NULL;
	GList *list, *link;

	g_return_if_fail (E_IS_PHOTO_CACHE (photo_cache));
	g_return_if_fail (email_address != NULL);

	/* This will be used to eavesdrop on the resulting input stream
	 * for the purpose of adding the photo data to the photo cache. */
	data_capture = e_data_capture_new (photo_cache->priv->main_context);

	g_signal_connect_data (
		data_capture, "finished",
		G_CALLBACK (photo_cache_data_captured_cb),
		data_capture_closure_new (photo_cache, email_address),
		(GClosureNotify) data_capture_closure_free, 0);

	async_context = async_context_new (data_capture, cancellable);

	simple = g_simple_async_result_new (
		G_OBJECT (photo_cache), callback,
		user_data, e_photo_cache_get_photo);

	g_simple_async_result_set_check_cancellable (simple, cancellable);

	g_simple_async_result_set_op_res_gpointer (
		simple, async_context, (GDestroyNotify) async_context_free);

	/* Check if we have this email address already cached. */
	if (photo_ht_lookup (photo_cache, email_address, &stream)) {
		async_context->stream = stream;  /* takes ownership */
		g_simple_async_result_complete_in_idle (simple);
		goto exit;
	}

	list = e_photo_cache_list_photo_sources (photo_cache);

	if (list == NULL) {
		g_simple_async_result_complete_in_idle (simple);
		goto exit;
	}

	g_mutex_lock (&async_context->lock);

	/* Dispatch a subtask for each photo source. */
	for (link = list; link != NULL; link = g_list_next (link)) {
		EPhotoSource *photo_source;
		AsyncSubtask *async_subtask;

		photo_source = E_PHOTO_SOURCE (link->data);
		async_subtask = async_subtask_new (photo_source, simple);

		g_hash_table_add (
			async_context->subtasks,
			async_subtask_ref (async_subtask));

		e_photo_source_get_photo (
			photo_source, email_address,
			async_subtask->cancellable,
			photo_cache_async_subtask_done_cb,
			async_subtask_ref (async_subtask));

		async_subtask_unref (async_subtask);
	}

	g_mutex_unlock (&async_context->lock);

	g_list_free_full (list, (GDestroyNotify) g_object_unref);

	/* Check if we were cancelled while dispatching subtasks. */
	if (g_cancellable_is_cancelled (cancellable))
		async_context_cancel_subtasks (async_context);

exit:
	g_object_unref (simple);
	g_object_unref (data_capture);
}

/**
 * e_photo_cache_get_photo_finish:
 * @photo_cache: an #EPhotoCache
 * @result: a #GAsyncResult
 * @out_stream: return location for a #GInputStream, or %NULL
 * @error: return location for a #GError, or %NULL
 *
 * Finishes the operation started with e_photo_cache_get_photo().
 *
 * If a match was found, a #GInputStream from which to read image data is
 * returned through the @out_stream return location.  If no match was found,
 * the @out_stream return location is set to %NULL.
 *
 * The return value indicates whether the search completed successfully,
 * not whether a match was found.  If an error occurred, the function will
 * set @error and return %FALSE.
 *
 * Returns: whether the search completed successfully
 **/
gboolean
e_photo_cache_get_photo_finish (EPhotoCache *photo_cache,
                                GAsyncResult *result,
                                GInputStream **out_stream,
                                GError **error)
{
	GSimpleAsyncResult *simple;
	AsyncContext *async_context;

	g_return_val_if_fail (
		g_simple_async_result_is_valid (
		result, G_OBJECT (photo_cache),
		e_photo_cache_get_photo), FALSE);

	simple = G_SIMPLE_ASYNC_RESULT (result);
	async_context = g_simple_async_result_get_op_res_gpointer (simple);

	if (g_simple_async_result_propagate_error (simple, error))
		return FALSE;

	if (out_stream != NULL) {
		if (async_context->stream != NULL)
			*out_stream = g_object_ref (async_context->stream);
		else
			*out_stream = NULL;
	}

	return TRUE;
}