Using Tumbler in Client Applications
Yesterday, Philip briefly wrote about Tumbler, the new D-Bus thumbnailing service that is going to be used on Xfce 4.8 and Maemo 6. Today, I'd like to explain how to use this service in client applications. Depending on the application type, the usage varies a little, so I'll focus on the basics here. I'll discuss some tricks at the end of this post though. What I'm not going to do is to talk about how to connect to D-Bus, how to call methods on D-Bus objects and so on. See the D-Bus tutorial or toolkit-specific documentation for more information about that.
A separate post with information on how to extend the thumbnail service will hopefull follow soon.
The Service Architecture
The thumbnailer specification defines four D-Bus service APIs. For most client applications only two of these are interesting: org.freedesktop.thumbnails.Thumbnailer1 (the thumbnailing service) and org.freedesktop.thumbnails.Cache1 (the thumbnail cache manager). The thumbnailing service can be used to request thumbnails and get feedback on the progress of requests. The cache manager can be used to keep the cache synchronized with the hard drive contents by notifying it when files are deleted, copied or renamed.
Thumbnail Request Workflow
Thumbnail requests include the following information:
- An array of URIs for which thumbnails should be generated
- An array of MIME types for these URIs (each element corresponding to the URI with the same index in the URI array)
- The thumbnail flavor to generate for the URIs (
normalis 128x128px,largeis 256x256px, ...) - The scheduling mechanism to be used for the request (foreground, background, ...)
- An optional handle of a previous request that should now be cancelled
Because the service implementation might vary depending on the system (right now there's only Tumbler, but who knows about the future...) there is no fixed set of thumbnail flavors and schedulers. The specification is supposed to define a standard set of flavors and schedulers that all implementations have to support (like a normal flavor and the scheduler default). The URI schemes and MIME types supported by the thumbnailing service also depend on the implementation and the availability of thumbnailer plugins and applications extendending the thumbnailing service via D-Bus. So, the first thing an application should do is to to determine which flavors, schedulers, URI schemes and MIME types are supported.
Determine flavors, schedulers, URI schemes and MIME types supported by the service
The thumbnailer service provides the methods GetFlavors, GetSchedulers and GetSupported for this. They all return string arrays with supported flavors, schedulers and URI scheme and MIME type pairs. GetSupported is a bit special, as it returns two arrays (one with URI schemes, the other with MIME types). These are to be interpreted as arrays of scheme/type pairs, each pair of which means that files with both the scheme and the MIME type at a certain index are supported. Applications can use this information to avoid requests for unsupported files. Once all this information is collected, we can continue with...
Requesting Thumbnails
Let us assume for a moment that only one thumbnail is needed and that the flavor we want is normal, the scheduler is foreground, the URI is file:///tmp/foo.png and the MIME type obviously is image/png. We can request a thumbnail to be created for this URI by calling the Queue method of ...thumbnails.Thumbnailer1 like this (written in some kind of fantasy language with dynamic D-Bus bindings ;)):
handle = service.Queue ("file:///tmp/foo.png", "image/png", "normal", "foreground", 0)
!["file:///tmp/foo.png"](http://gezeiten.org/post/2009/10/"file%3A///tmp/foo.png"){kind=link}
As you can see here, requesting thumbnails for more than this one URI is simple: just append one more URI to the first array and one more MIME type to the second array.
If you perhaps need to cancel the request later, remember the handle returned by the service. In complex applications with asynchronous APIs you'll sometimes need to link internal request handle to thumbnailer service handles, so the handle returned by the service is not only useful for canceling requests.
Being Notified About the Progress of a Thumbnail Request
Once you have requested one or more thumbnails, you'll probably want to be notified about the progress of your request. Tumbler will emit D-Bus signals for the following status updates:
Startedis emitted together with the request handle as soon as the service starts processing the URIs of the request.Readyis emitted together with the request handle and an array of URIs whenever the thumbnail for one or more of the URIs of the request were generated and can now be used. The array passed to you contains the source URIs, not the URIs of the thumbnail files.Erroris emitted together with the request handle, an array of URIs, an error message and an error code whenever the generation of a thumbnail for one or more URIs of the request failed.Finishedis emitted together with the request handle once the thumbnail service has finished processing the request. This can happen when all URIs have been looked at or when the request was cancelled.
Please note that there is no guarantee for the Ready and Error signal to be emitted for all URIs of the request if the request is cancelled. So, if you maintain an internal thumbnail state for URIs depending on the thumbnail progress, you'll have to remember which URIs were queued. In any case you're advised to make sure to free up your own resources in case the service dies or D-Bus crashes. This can be achieved using a timeout (which will also be helpful if the service hangs) or by connecting to the destroy signal of the DBusGProxy (or whatever equivalent D-Bus API is used in your application).
Cancelling Requests
If you want to cancel certain requests, all you need to do is to call the Dequeue method of the service and pass the correct request handle to it.
Loading the Thumbnails
Where to look for the actual thumbnail files after they have been generated depends on the platform. If Tumbler is built with the default cache backend (which should be built on normal desktop systems), files are stored according to the thumbnail managing standard. On Maemo, files are stored as JPEGs. Philip might be able to give a more detailed description about how to access them.
Thumbnail Cache Synchronization and Cleanup
Some applications like file managers or image viewers allow users to rename, copy, move or delete files on the disk. Since renaming, copying and moving doesn't affect the contents of a file, you can avoid to regenerate its thumbnail by notifying the thumbnail cache of this change. When a file is deleted the thumbnail is no longer needed, so in order to prevent the cache from being polluted with dead thumbnails, you can notify it as well.
This is what the ...thumbnails.Cache1 service interface is for. It provides the following D-Bus methods for the above scenarios:
Copy (string array from_uris, string array to_uris)Move (string array from_uris, string array to_uris)(this one is useful for both moving and renaming)Delete (string array uris)
If you want to clean up the cache in a more general sense by deleting very old thumbnails you can do this via the following method which deletes all thumbnail whose original files have not been modified in a long time and have a certain URI prefix (which may be empty):
Cleanup (string uri_prefix, uint64 original_mtime_threshold)
The above should give you an insight into how the thumbnail service can be used in applications. If you have any questions about this, please let me know. Ok, now let's reveal some tricks to perform optimization on the client side.
Tips and Tricks
- Use asynchronous D-Bus calls in your application to avoid your application to block. A separate worker thread might also be useful.
- It's wise to cache the arrays returned from
GetSupported,GetFlavorsandGetSchedulers. ASupportedChangedsignal is planned to allow applications to update their cached information when the thumbnailer is extended by additional URI schemes or MIME types at runtime. - If your application generates a lot of thumbnail requests, as file managers and picture viewers with gallery support usually do, you'll probably want to reduce the amount of messages being sent over D-Bus. You can do this by grouping individual requests. Often when you use a
GtkTreeViewor something similar involving stateless cell renderers, the easiest way to generate thumbnail requests is when the cell renderer renders a file icon. If you don't group these individual requests, the system might go nuts. So, to group these requests you could use a worker thread with a wait queue that is flushed (URIs in it are sent to the thumbnail service as a single request) at most every X milliseconds. When the first thumbnail is needed, you start a one-shot timeout handler that is executed after X milliseconds, grouping all URIs added to the wait queue in the meantime. I do this in Thunar and it has proven to work well. It also scales nicely by grouping more efficiently the more thumbnails are needed in the time slot. Heavier user scrolling won't make things worse.
I guess that's it for now. I hope you enjoyed reading this first real post about Tumbler coming from me (which is also pushed to Planet Maemo by the way). Again, if you have any questions, please let me know.
R700, KMS, 3D, SSD, and other hardware
Gosh, just look at all the buzzwords in the title!
As you may have guessed, I'll be talking a bit about the recent developments on the FOSS drivers for RadeonHD cards, specifically for R700 cards. And some other hardware stuff.
Radeon
Yesterday, October 3, I made some big ol' changes to my workstation.
I decided to try out the new video driver stack that all the kids have been talking about. Kernel Mode Setting, git Mesa/xf86-video-ati/libdrm, git kernel 2.6.32_rc1-git3. All that jazz. I wanted to see if the 3D and KMS features were really working on my RadeonHD 4550 or not. I normally run a stable graphics stack, with ~arch Mesa/x86-video-ati/libdrm where necessary to keep up on 2D acceleration and features.
This was a big leap for me. So I first consulted some of the X11 team members, remi and nirbheek, who were quite helpful. I installed the latest git-sources kernel, which at the time was 2.6.32_rc1-git3. Mike Pagano has since added -git5. Next, I downloaded the individual -9999 ebuilds for the git master packages from the X11 overlay, stuck 'em in my local overlay, and merged 'em. Only thing left to do was reboot.
Lemme tell ya -- KMS in action is awesome. The console output is just beautiful, and there's no more flickering when SLiM and Xfce load.
I did notice some minor graphical corruption of the default mouse pointer. However, the corruption isn't present when using any pointer but the default "arrow", and it also isn't seen when hovering inside a Firefox window. I was told this is because Firefox uses its own cursors. Anyway, I reported the bug upstream.
Disclaimer: I know glxgears isn't a benchmark. But folks always want to know its results anyway. I tried running glxgears, which gave me a result of over 1300FPS with desktop compositing activated. My window manager is xfwm4, so all compositing is via Xrender, not OpenGL. Disabling compositing resulted in a 500FPS boost to over 1800FPS. What's this mean? Who knows. Probably nothing. Moving on.
I took the advice of my fellow developers on IRC and installed quake3-demo. Couldn't run it, though. It blanked the screen, then a message from my LCD firmware appeared, some kind of "input not supported" or "input not detected" error. It slowly repeated the window, drawing it from center to the top right. I had to Ctrl-Alt-Bksp to get to the console. It also locked up SLiM in the background, pegging one of my CPU cores at 100%. At this point, I rebooted just to test that KMS was still working, then called it a night.
Today, I revisited my pointer corruption bug and tried the workarounds posted by Alex Deucher. To my surprise, each one worked! Booting with radeon.modeset=0 removes the glitch, though it makes each boot extremely ugly, of course. Specifying EXANoDownloadFromScreen "true" in /etc/X11/xorg.conf also fixes the corrupted pointer, though it may also be slowing down all screen drawing operations by the tiniest bit. The jury's still out on that one; it may just be my imagination. I decided to keep this second fix, as KMS is just too glorious to throw out. I like pretty boots.
I also revisited quake3-demo, since I found some pointers on the Phoronix forums that had a workaround, which is to run OpenGL applications prefixed by LIBGL_ALWAYS_INDIRECT=1. To my surprise, this worked nicely. I tested resolution has high as 900-something by 720. My screen is 1440x900, but I haven't felt like pushing it that far, yet. The game is fluid and playable. I need to figure out how to display FPS so I can properly record what I'm seeing.
With the success of Q3demo, I remembered that QuakeLive has recently added Linux support. I installed the add-on for Firefox and tried it out. Works nicely, though I'm also running Firefox with LIBGL_ALWAYS_INDIRECT=1 just to be sure. As Alex Deucher and John Bridgman have pointed out on the Phoronix forums, that variable really isn't the safest thing to do, since if something crashes it can take down the whole X server, not just the application. However, it's also the only way I get working 3D games.
QuakeLive is pretty playable, though the framerates in a few places aren't smooth -- I can't tell if this is because of my card's capabilities, or the driver stack, or the whole weird idea of playing a 3D first-person shooter inside a web browser. 
The big problem with QuakeLive is that the sound is terribly distorted: the voices are greatly drawn-out and slowed down, like playing an old tape recorder at 1/4 speed. There are some solutions on the QL forums, but they're mainly for Ubuntu/Pulseaudio users. I haven't found anything that works for me, yet. The effects and music are okay; it's just the voices that lag horribly.
I've also installed the latest Nexuiz, version 2.5.2, in anticipation of future testing. One of these days I'll reinstall UT2004, but I haven't read any succesful reports of that game on R700 cards. There's a lot of testing to do in the future!
Overall, I'm thrilled with the new driver hotness for my ATI card. I bought it specifically because I knew the 2D support at the time was excellent, and because there would be so many good things coming down the way for other features, including 3D acceleration. (Yes, just like the latest XKCD strip. I swear, it's like that guy listens to everything I say and watches everything I do. It's really spooky!)
Hats off to all the developers for making it happen. Many thanks!
SSD
After August's fiasco with a defective SSD, I decided to use my refund from the RMA and order a different SSD a few days ago. This time I've settled on a SanDisk enterprise SSD from an HP blade server. Only cost $49, no shipping charges. Brand new. eBay for the win.
It packs 16GB of SLC flash, which makes it perfect for mounting /usr/portage and /var on it. This way I can feel free to sync whenever I want, instead of only once a week or more. My system drive uses MLC flash, so I've been trying to ease the write load on it, which means putting the high-write activity on a dedicated disk.
The SanDisk SSD "only" has sustained reads/writes at 60MB/sec, but that's plenty for syncing Portage, as the real limiter is not how fast data can be dumped to the disk, but how fast the rsync servers can send it to my box. Same for /var writes -- it's mostly just log files and some tiny temp things, as /var/tmp is already mounted on a RAMdisk. No large files that need >100MB/sec bandwidth. I'm lookin' forward to shovin' it in my box!
More hardware
Since September 28 was my birthday and all, I've been treating myself to various bits of cheap hardware. Like a replacement AC adapter for my DC PicoPSU. The current AC brick is rated at 102W, which is way more than I need, but the problem is that it spins up its tiny fan at only 50%-75% load. This means that opening up a bunch of tabs, compiling packages, playing Quake, watching large-sized Hulu videos and whatnot turns on the fan right away. And it's the world's most annoying fan. It's loud, whiny, it hisses, and it blows the bad smell of very hot electronics out into the room. Lemme tell you, hot plastic and PSU guts do not smell good.
I just ordered a replacement fanless adapter. This thing is high-quality, designed to run very cool. And it's rated at 150W output, meaning it can match my 150W PicoPSU. My max system draw is maybe 60W, but I'll have overhead room in case I ever feel like upgrading a key component somewhere.
I also bought a $40 wireless router, an Asus WL-520gU. I already have a WL-500gP v2, which I hacked and flashed with DD-WRT a long time ago. This new router is so that I can hook up my Xbox 360 to the network without having to run 50 feet of cable across the carpet. I chose the 520gU instead of the gC because the gU supports Xlink Kai, which seems pretty cool to me, as I don't have a Gold Live account. Yay for tricky internets. Apparently it's pretty common to buy a cheap wireless router and put it into client mode, rather than buying the $100 official USB dongle . . . which doesn't even support WPA2-AES or any decent security. Asus routers are known for excellent open-source support, and I've had nary a complaint about my current one. Yay for Linux on routers! Yay for online gaming!
* * *
Oh yes, and before I forget, this month's Xfce desktop:
It's October, but my current desktop is so pretty (gallery link) I haven't felt the need to switch for the last couple of weeks. There's another clean version that just shows off the wallpaper in my devspace.