AsyncImage is a Gtk.Image that provides a way to load icons and images asynchronously without blocking the main GTK thread.
AsyncImage can be used to improve your GTK interface's performance that has a lot of images to load and populate e.g: the applications menu and an icon chooser.
Primarily the Gtk.Image loads it's surface synchronously and blocks the main GTK thread which can cause significant slow downs and lagging. The AsyncImage is a wrapper for the Gtk.Image and provides with two main methods: Granite.AsyncImage.set_from_gicon_async and Granite.AsyncImage.set_from_file_async.
AsyncImage internally operates only on Gdk.Pixbuf and Cairo.Surface's which means that you cannot read valid properties from the main Gtk.Image like Gtk.Image.icon_name, Gtk.Image.gicon or Gtk.Image.file. The only property which will be set is the final surface: Gtk.Image.surface.
Even though AsyncImage sets only the Gtk.Image.surface, it automatically detects changes to the underlying Gtk.Widget.scale_factor and reloads the icon to a new scale factor when it changes. If you request to set an GLib.ThemedIcon and the icon or GTK theme changes the AsyncImage will also reload it to display the new icon with applied changes.
The Granite.AsyncImage.gicon_async and Granite.AsyncImage.size_async are properties which reflect the current icon and it's size which will or is currently displayed. Note that those two properties will return meaningful results only when you call Granite.AsyncImage.set_from_gicon_async and it's wrappers.
AsyncImage has also its own cache for already loaded icons. If you attempt to load the same icon at the same size AsyncImage will look it up and if it's available, will set it immediately.