• You’ve probably already noticed, but the “qt-kde” module on git.kde.org is no more, and has been moved to be “qt”, a simple clone of Nokia’s Qt 4.8 (and prior) codebase (there’s no mirror of the upcoming even-more-split Qt 5 in development yet). What this means for kdesrc-build users is that they need to adjust their qt-copy module. Unfortunately the module used to build Qt must still be called qt-copy to avoid breaking things.

• The on-disk layout for source and build directories for modules that come from the KDE project database (i.e. repository kde-projects) has changed. Now the destination directory uses the same path that is present in the hierarchy on projects.kde.org. As an example, kdelibs would be in $src-or-builddir/kde/kdelibs, kdesrc-build would be in $src-or-builddir/extragear/utils/kdesrc-build, etc. This should make it easier to manage the increased number of modules resulting from the move to git.kde.org.

  • To make this easier, kdesrc-build will move your old source and build directories (if they’re detected) when this happens, so you shouldn’t have to waste all your bandwidth or spend an inordinate amount of time rebuilding modules.
  • One problem that was noted with this new arrangement is that it’s possible to have git checkouts nested in other git checkouts (for instance, konsole fits in kde/kde-baseapps, but kde-baseapps is a separate git module). This is not a problem by itself, but can interfere with older checkouts of kde-baseapps. So 1.14.1 introduced the ability to delete existing source directories if they would be in the way of a git-clone. You must pass --delete-my-patches to enable this due to the obvious hazard of losing uncommitted work.
• A manpage was added, which might prove useful if you don’t have a web browser handy, Internet connection to docs.kde.org, etc. The catch is that the manpage is generated using the KDE docs infrastructure from kdelibs, which might not be present yet when you first run kdesrc-build! ;) Don’t forget to have your MANPATH set to include your KDE man directory.
• As pointed out in an email by Aaron Seigo to kde-buildsystem some time ago, it really could be easier to setup kdesrc-build on initial run. To that end, a script called kdesrc-build-setup is included. It’s generated config is *very* simplistic at this point but it’s better than what was there before. To allow for bootstrapping a GUI without having KDE installed the setup script uses the console just like kdesrc-build.
• kdesrc-build makes the kde: Git alias (which is recommended by git.kde.org admins) available if you haven’t set it up yet.
• The use of git snapshots is supported for git-clone now, but only for modules from the KDE project database. My understanding is that this should save CPU load on the git.kde.org infrastructure (although not much in the way of bandwidth). Resuming of aborted downloads is not supported yet unfortunately. If this causes problems use ‑‑no‑snapshots to disable (as of 1.14.1, where that option works again…).
• You can include other files in your configuration file, for those who actually use the kdesrc-build feature supporting different configurations depending on what your current directory is.

• As a final excerpt, it is possible to ask for all modules under a given KDE project module to be built. This is actually required for kdegraphics (at least when I implemented this) since kdegraphics supports a SuperBuild-style repository which will check out all of its dependent submodules and build it for you. You can also build the submodules individually, so to keep people from accidentally building them both the kdegraphic base repo is marked as inactive in the database which prevents automated tools (including kdesrc-build) from processing it.

  By using something like:

  module-set graphics
      repository kde-projects
      use-modules kdegraphics/libs kdegraphics/*
  end module-set

  you can for kdesrc-build to build all “active” modules under kdegraphics, even if kdegraphics is itself marked inactive. (The kdegraphics/libs part is to force kdesrc-build to build that first, kdesrc-build will skip duplicate modules so you don’t need to worrk about kdegraphics/* trying to build /libs twice).

• There’s actually a few more minor things but this post is already too long!

There’s fewer “pure bugfixes” than I expected, but environment variable handling support is improved somewhat, and the KDE project database is actually downloaded in pretend mode when it’s needed (just like the prompt had been saying was happening…).

There has been a fairly substantial refactoring/code reorganization to get to this point. The test suite does pass, but if you’re a heavy user of the kde-languages option you may want to wait until I’ve verified that the l10n building still works (unfortunately cloning such modules makes testing that option more difficult than I’d like).

Other than that I hope you all will be happy with the capabilities of the latest version. I’ll try to release more frequently than every 6 months in the future, that might be a bit easier to achieve at my new duty station near Washington, DC.

I achieved a large milestone today in finally managing to group together the debugging methods in a way which remains compatible with the rest of the script.

What I mean by this is that I used the prototypes feature of Perl subroutines to allow for methods like:

return 1 if pretending;

(Notice how there are no parentheses after the pretending call), and

info "\tPerforming source update for g[$module]";

(Likewise no parentheses for the info method call).

Now, in retrospect I probably should have simply not used prototypes, at least for the output methods which would not be significantly less readable with parentheses. All the same however, prototypes were interfering with grouping these debugging routines into their own module.

This is because subroutine prototypes actually affect the Perl parser itself, and these prototypes are not exported by the normal Perl routines for exporting subroutines out of classes, i.e. a subroutine Debug::pretending() (with a prototype that is completely empty) would get exported to main as main::pretending (with no prototype at all). This would break code that used the pretending routine without parentheses since the Perl parser doesn’t know it is supposed to accept no arguments.

After beating my head on this problem off-and-on for awhile it finally occurred to me today that Perl is a “dynamic language”: Why couldn’t I just manually feed the appropriate declaration into the parser on-the-fly when necessary?

After some prototyping I came up with an import method that seemed to work:

my $pkg = shift;
my $caller = caller;
my @exports = qw(debug pretending); # etc...

# This loop is only slightly "magical". Basically to import functions
# into a different package in Perl, we can use something like:
# *PACKAGE::FUNCTION = \&SOURCE_PACKAGE::FUNCTION;
# where the *PACKAGE modifies the symbol table for that package.
#
# The extra part, which requires using eval, is to predeclare the
# subroutine with a prototype first.
# "sub foo($old_prototype);"

for my $fn (@exports) {
    my $prototype = prototype($fn);
    eval "sub ${caller}::${fn}(${prototype});\n" .
         "*${caller}::${fn} = \\&${pkg}::${fn};";
}

All that I’m really doing is reading in the prototype for each function that is exported by using the built-in prototype method, and then eval-ing a string the predeclares the exported subroutine with the appropriate prototype, and then assigns the implementation of that subroutine to the existing package’s implementation.

This exports the prototype information when the import method is *run*, but the Perl parser will parse as much of the file as possible before starting execution. So if we want the parser to be updated as well, we must force the new import method to be run as soon as possible, which can be done using the standard Perl BEGIN { ... } block, which runs the code inside of it as soon as it is encountered.

So in kdesrc-build, instead of having “use ksb::Debug;“, I have:

BEGIN {
    ksb::Debug->import();
}

And now everything is parsed (and run) just as before! I’ll likely still convert the code to not need this circumlocution at some point, but I thought it was at least technically interesting.

So, kdesrc-build 1.12.1 is upon us (the link may be broken, I’ve just committed everything to svn, it should update within a few minutes of that). I probably shouldn’t have made it a mere +0.0.1 release, as it contains one notable large new feature, and several minor improvements besides the normal bugfixes.

The big deal is the module-set feature I discussed a couple of months ago. This allows for easy declaration of git-based modules in your .kdesrc-buildrc (which is good, as old Subversion modules are being migrated quickly now that 4.6 has been branched off of trunk).

However, it is not a long-term (or even a good medium-term) solution. To that end, the KDE sysadmins have been working hard on making a database of the projects available on git.kde.org, including what groups each repository falls under. Besides being needed to migrate some of the tools that we currently use with Subversion, it will be useful for allowing build scripts (such as kdesrc-build) to take a command to build e.g. “kdepim”, and figure out the full list of git repositories contained in the “kdepim” grouping.

The groups can themselves be contained within groups (in theory you’d be able to build all of extragear with a single command, although I’ll probably block groupings that large like kdesrc-build currently does to avoid users accidentally DoS-ing KDE resources).

That will be the next thing I start on. Hopefully finding good Perl libraries for parsing XML doesn’t take too long. ;)

The other thing I will be doing is migrating to git.kde.org myself. I’m not exactly sure when, but I already have the rules mostly written. Perhaps I’ll wrap everything up this weekend and move to git.kde.org myself.

Either way, let me know if there are issues with the new release (it’s been brewing for about a week so don’t say I didn’t give trunk users time to test! ;)

Happy building!

PS: Special side note, if you’ve been receiving messages about KSharedDataCache saying that “This cache is probably corrupt”, update kdelibs to either 4.6 branch or trunk, that bug should be fixed now…

But in the meantime, I’ve written some code to allow you to at least quickly declare KDE git modules to build. I’ve just committed it to trunk kdesrc-build (in kdesdk/scripts). This feature adds two options:

1. git-repository-base, which declares an alias name for a new git repository, and assigns it a URL. This is needed for a concept I’m calling “module-set” for now.
2. use-modules, which is used in a given module-set to name the git modules that you want to build at that point in the .kdesrc-buildrc, in order.

Simple example:

global
...
git-repository-base kde-git git://anongit.kde.org/
end global

# Need to set options for attica? Just declare it manually and set the options after the
# module-set. It still gets built before soprano though.
module attica
cmake-options ....
end module

Hopefully this makes managing the large numbers of individual git projects that are popping up much more reasonable. Another long-term measure is that some motivated git-transition types are working on a module-grouping XML format, which will be usable by kdesrc-build (among other software) to quickly group related git modules under a single name.

What this means for you if you use kdesrc-build is that you should probably update your ~/.kdesrc-buildrc to add the projects separately since they will no longer be built as part of kdesupport.

Affected are Akonadi (the underlying PIM layer, which might be required for kdelibs, I forget), Attica (“Implements the Open Collaboration Services API”, I assume this means it’s required as well) and Soprano (C++ RDF framework, used for Nepomuk. I believe Soprano is required even if Nepomuk is not being used, but that could also be wrong).

My recommendation is to add the following modules after your existing kdesupport module, before any other modules:

module soprano
    repository git://git.kde.org/soprano.git
end module

module attica
    repository git://git.kde.org/attica.git
end module

module akonadi
    repository git://git.kde.org/akonadi.git
end module

Naturally if you will be doing development on these repositories and not simply checking out a read-only copy for build purposes you should use the git@git.kde.org:foo.git form of the repository URL.

This migration to git has the potential to get annoying for end-users, especially as we modularize more and more. To that end, the KDE Sysadmin team is working on a specification for grouping related modules together, which kdesrc-build will support, that way you could just do something like:

kde-module-group kdeplatform
    # References known XML module grouping
end kde-module-group

and things would Automagically Work. Stay tuned…

I managed to confirm the issue. Turns out that when I ported KIconLoader to use KSharedDataCache, I didn’t employ KIconLoader’s other cache (a pixmap cache [1]) in all the instances where it made sense. Specifically, the pixmap cache only had things added when an entry was also added to the KSharedDataCache.

But this doesn’t always make sense. The KSharedDataCache is shared across all KDE Platform-based processes, but there’s a different pixmap cache for every KIconLoader. So, it’s perfectly possible to have many processes never have to add an icon to the KSharedDataCache.

Now, new pixmaps that are read from a KSharedDataCache are added to a KIconLoader’s own personal pixmap cache to avoid trying to search the KSharedDataCache next time. This has the potential to significantly speedup icon-based operations, especially in situations where an application uses the same pixmaps over and over. This speedup is in trunk (future 4.6) and will also be released with KDE Platform 4.5.2.

Matthias (and Ingo Klöcker) provided another speedup, by converting some slow QString-based operations to use a QStringBuilder class introduced in Qt 4.6. This gave an 8% speedup on an icon microbenchmark, so not insignificant. This one will only be in KDE Platform 4.6 at this point, although I wouldn’t feel horrible if it were to be backported also.

Incidentally, this was the first I’d heard of regarding QStringBuilder, so it’s something I’d recommend brushing up on if you haven’t heard of it yet. The QStringBuilder documentation is part of the QString API reference (search for “More Efficient String Construction”).

[1] Every KIconLoader instance also has its own pixmap cache, which holds QPixmaps, while KIconLoader’s KSharedDataCache holds QImages.

First off, I have renamed kdesvn-build to kdesrc-build to reflect the fact that it builds from Git-based software repositories. In conjunction I released kdesrc-build 1.12 which has various minor improvements, including a few Git improvements.

I’ve complained about my car breaking down. It’s fixed, although I will be selling it now (my wife and I were debating the merits of getting an improved car for awhile before, this incident sealed the decision).

Just today I’ve committed a new feature to JuK, the sadly neglected KDE Software Compilation music manager. Now you can use the scroll wheel in the track announcement popup to quickly switch tracks without having to use the Next/Prev buttons. It’s probably already in every other media player with a playlist, but it’s at least in JuK now. Note that this is a 4.6 new feature, not 4.5.

I’ve also been “reviewing” a patch to further remove Qt3 support code from JuK, which I will try to clean up and get comitted this release cycle. The big thing I still need to do is to finally convert from K3ListView to a real Model/View architecture to finally be rid of Qt3Support. Help is always appreciated btw =D

Burkhard Lück, the documentation super-hero, has been improving JuK documentation for me, but I still need to make some changes that he’s requested to bring the docs closer to 2008-era (let alone 2010) :(

That’s another good “intro to KDE Platform” kind of job by the way, it’s how I got introducing into coding for JuK myself. ;)

kdesvn-build has already supported git (and the upcoming 1.12 release has some git improvements), so building and installing konversation and amarok is as simple as fixing your kdesvn-buildrc to refer to the correct git repository. For Amarok and Konversation this means changing gitorious.org to git.kde.org for most users using the read-only clone URL (like git://gitorious.org/amarok/amarok.git). Read-write access occurs with a separate URL, lookup the TechBase entry for more info.

If you have already built a gitorious version of Amarok or Konversation then you have two options to correct the downloaded source:

1. Remove the source directory, and kdesvn-build will clone it again from the updated repository, or
2. Use the a manual git remote URL updating command as described on the Konversation homepage.

It has been awhile since a release of kdesvn-build, and the kdesvn-build website was recently effectively offline due to an IP address change, so I’ll probably move to more stable KDE-hosted servers if possible. With all that in mind, it’s probably time to change the name again! (Who remembers kdecvs-build? ;)

My initial plan for the name is kdesrc-build. I figure there’s no way this one won’t be future-proof (and besides, svn will still be supported for some time probably). ;) If anyone has better ideas for a name that is descriptive, relatively future-proof, and catchy, please leave me a suggestion in the comments.

While I’m polling the audience, I’ve been thinking about the design of kdesvn-build. Right now it is a 217 KiB single-file Perl script, with no external dependencies required aside from Perl 5.8. This is mainly to make it as easy to install and upgrade as possible. Does this ease of upgrading actually make a big difference for you all? It hasn’t been very difficult keeping the script in one file (I even managed to get Perl’s weird object orientation to work in one file) so I can keep that going if it’s worth it.

Defragmentation

One of the sub-optimal parts of my implementation of KSharedDataCache is the fact that the data must be contiguous in memory. It would actually be fairly simple to change this due to the existing page design, but right now this is what we’ve got.

The reason this is sub-optimal is due to an effect called fragmentation (more precisely, external fragmentation). The effect is illustrated in the following diagram:

The problem with fragmentation can be seen in the cache layout at the bottom. The maroon blocks indicate allocated pages. In the bottom cache layout, even though the overall allocation is less than in the other cache, it is not possible to fit the new block in memory because there is no solid block of free memory of sufficient size.

This problem could be solved if only there were a way to move the allocated memory around. In the case of KSharedDataCache this can be done, because only the cache records the location of each data block (when an item is returned to an application, it is actually a copy). This process is called defragmentation, and is essentially the same idea as what disk-based defragmenters do.

My defragmentation is probably fairly naïve but does the job, simply looking for used pages of memory and moving them as far to the beginning as possible. The more interesting part is deciding when to defragment. Right now defragmentation is performed as follows:

• When we are having to remove currently-used pages due to insufficient consecutive memory when total free space is higher than a certain threshold, before pages are actually removed.
• After evicting cache entries, since there are probably more holes in memory, and the reason we evicted things from the cache was due to insufficient consecutive free memory.

As I said my defragmentation routine is very simple and could probably be easily improved. I haven’t noticed issues with it becoming a problem during desktop usage but that’s perhaps attributable to not coming into use very often (if at all) due to the cache aging I mentioned in Part 3.

Porting KIconLoader

Perhaps the largest impetus driving me to do all this work in the first place was due to KIconLoader, which used to use KPixmapCache to cache loaded icons. KIconLoader is used everywhere in KDE and so many KPixmapCache-related crashes were first noticed in seemingly very-unrelated applications when trying to load icons.

Porting KIconLoader to KSharedDataCache was not a direct method name replacement unfortunately, as one of the things KIconLoader stored was the path that the icon was found at. (This used to be done by using the custom data API for KPixmapCache I mentioned in Part 1). I had first intended to use KImageCache (an image-related subclass of KSharedDataCache) for KIconLoader, but I ended up using KSharedDataCache directly, to hold cache entries that simply contained the pixmap and the path.

One problem that came up that I only fixed a few minutes ago was that KIconLoader would not only cache loaded icons, but it would also cache failed icon lookups, which was a behavior I had not ported over. This was especially notable in Dolphin browsing in large directories apparently. Either way, that is now fixed.

Future Directions

I’m proud of the work I put into KSharedDataCache, and especially since it has been running in trunk for about 4 weeks now with no major issues that seem to have popped up. However there are quite a few things that could be improved about it:

• Cache corruption: Although in my opinion the risk of crashes from a corrupted cache is less right now due to the cache layout and non-usage of QDataStream, the possibility is not zero. Because of the serious consequences of cache corruption leading to crashes, it would be nice to have an efficient way to mark that a disk cache should be deleted because it is corrupt. I’ve thought of some things but have no concrete plans at this point.
• The page table/index table method of storing data is very simplistic. There is surely a more appropriate method buried in some ACM or IEEE publication somewhere, even in the limits of fixed memory size. As it stands my method blends some of the disadvantages of 1960′s-era memory allocators with paged memory allocators, without all of the benefits.
• Assuming defragmentation remains required, the defragmenter could probably be made faster as well.
• It is not at this point possible to resize a cache once it has been created. There’s no reason in theory that it can’t be done, it’s just not implemented. (Note that implementing this is more complicated than simply changing a size flag in the cache…)
• The cache could possibly be made more concurrent with lock-free algorithms or finer-grained locking. This is not something I’d like to touch until I have a way to verify correctness of the result, however.
• Finally, it possible that someone has done this way better and that I simply missed it, in which event we should look at whether we should just adopt that library as a dependency and make KSharedDataCache a wrapper around it.
• Should we remove old KPixmapCache caches after starting up a shiny new 4.5 desktop?

So, this concludes my series on implementing a shared cache. I’ve got to get working on other efficiency improvements, new kdesvn-build releases, classes, etc. It’s been fun writing though!

Pointing to things in shared memory

First I’ll talk about pointers. Essentially all you need to know about them is that a pointer holds a memory address, namely the address of the data you’re really interested in.

Now, every process in modern operating systems has its own “address space”, which defines where things are in memory. So, memory addresses in process 1 have no relation to addresses used in process 2, or any other process.

What this means for shared memory algorithms is that you cannot use normal pointers, since they rely on pointing to a specific spot in a process’s address space. See below for an example:

Three KSharedDataCache-using processes are running, and let’s say that kcalc was the first to create that cache, so the pointers are created from the perspective of kcalc’s address space. If KSharedDataCache used normal pointers to point to the data in the cache (from the cache header) then things would fail to work right in kate where we point into the middle of the data. The case of krunner is even worse, as we point into the krunner process’s private data!

The solution is not too hard. The memory map call that creates the connection will tell you where the connection starts. So instead of saying “the data is at address 0×400000″, use pointers that say “the data is 1024 bytes past the start”. These are called offsets. For example, the pthread library that is standard in POSIX could use this type of technique to implement “process-shared” mutexes (mutexes are by default merely thread-shared).

Initial cache setup

Taking that first step in creating a cache is hard. Once the cache is setup we can rely on having some means of locking, entry tables that are setup, and other niceties. Creating that in the face of race conditions is another matter though.

My decision to use pthreads for the mutex made this part harder than it could have been otherwise, as the mutex has to be stored with the cache. But you can’t use the mutex without initializing it first (remember that pthread mutexes default to not being process-shared). If two processes try to create a non-existing cache at the same time, they would both try to initialize the mutex, and the process that initializes the mutex the second time could potentially cause logic errors in the first process.

So, I went with a simpler solution for this rare case: A spinlock, using Qt’s built-in atomic operations. It is not quite a pure spinlock because there are a couple of possibilities (numbered as they are in the code):

Case 0 is that the cache has just been created, without ever having been attached to. (0 because that is the default value for an initially empty file that has just been mapped into shared memory).

Case 1 is that there is a process which has noticed that the cache is not initialized, and is initializing it (in other words, it atomically switched the 0 flag to 1). This is a locking condition: No other process will attempt to initialize the cache. But the cache is not initialized yet!

Case 2 occurs when the cache has been finally initialized, and can have the standard locks and methods used. To access a cache that is in this condition you must use the cache mutex.

I don’t use a spinlock all the time because my implementation does not do any magical non-locking algorithms, and therefore some operations might take some significant time with the lock held. Using a mutex allows threads that are waiting to sleep and save CPU and battery power, which would not work with a spinlock.

Cache handling

Any cache needs a method of deciding when to remove old entries. This is especially vital for hash-based caches that use probing, like KSharedDataCache, where allowing the cache to reach maximum capacity will make it very slow since probing becomes both more common, and more lengthy. I use several techniques to try to get rid of old entries. I make no promises as to their effectiveness, but I felt it was better to try something than to do nothing. The techniques are:

• Limited Quadratic Probing: One standard method of handling items that hash to the same location in a hash table is to use “probing”, where the insertion/find algorithms look at the next entry, then the next, and so on until a free spot is found. Obviously this takes longer, especially if the hash function tends to make entries cluster anyways. In the case of KSharedDataCache it’s perfectly acceptable to simply give up after a certain number of attempts, and I quite willingly do so (but see the next technique). On the other hand if you can avoid colliding you don’t have to worry about finding empty spots, so to that end I use the “FNV” hash function by Fowler, Yo, and Noll.
• Ramped Entry Aging™: The basic idea is that as the amount of entries in the cache goes up, it becomes more likely that the insertion method will, instead of probing past a colliding entry, artificially decrease its use count, and kick it out if it becomes unused. There are competing effects here: There’s no point having a cache if you’re not going to employ it, so this aging never happens if the cache is lightly loaded. On the other hand entries that get added to the cache and only ever used once could cause collisions for weeks afterwards in the long-lived scenarios I envision so it is important to make entries justify their use. So as the cache load increases, there is a higher and higher chance of entries being evicted if unused. I simply divide the use count in half, so an entry can be quickly evicted even if used a million times a month ago.
• Collateral Evictions®: In the event that the first two options don’t work, then some entries have to be kicked out to make room for new ones. This process is called eviction. In my Collateral Evictions plan, anytime we kick entries out, we kick even more entries out on top of that (I chose twice as many, for no particular reason). The idea is that if we’re running of out space we’ll probably have to kick someone else out on the very next insert call anyways, so since it’s a time-consuming operation we might as well make it effective. The exact entries that get kicked out are decided based on the developer-configurable eviction policy.

Next time I’ll talk about defragmentation, porting KIconLoader, and any other random things I can think up. I hope it hasn’t been deathly boring so far!