libblockdev 2.0 released

Today a new major version of the libblockdev library was released - libblockdev 2.0. This new release breaks the C API [1], but for the sake of important new features that required such changes. So what's new?

Read-only pointer arguments marked as const

Arguments that are pointers to data which functions don't modify are now marked as const. This doesn't change the functionality in any way as no libblockdev functions used to be modifying such data before (except for out parameters, of course), but it introduces a clear and explicit contract between the caller and the callee.

Extra arguments for functions

Some functions have a new argument const BDExtraArg **extra where BDExtraArg is just a struct of two strings - a key/option and a value - and thus the whole thing is a NULL-terminated array of key-value pairs. This way the caller code can pass extra information to such functions without every single possible option being a separate argument. Something like what Python has with **kwargs and what DBus has with a{sv} extra arguments, but restricted to strings. Right now all functions taking the extra argument just pass the key-value pairs to the utilities they run (and thus valid keys/options are those supported by the utilities), but when functions are reimplemented using other libraries, syscalls or anything else than forking and execing utilities, all the key-value pairs will be interpreted in the same ways.

Progress reporting

All functions that perform some actions or changes (simply put, those that do not just read and return some information) report progress now. No miracles happened behind the scenes so very often the progress is just like "Something started [0]" and "[0] Completed" [2] with nothing in between, but there are exceptions like the lvm_pvmove() function (and some others) that really report progress while the action/change is being performed. In order to avoid complicating the API and adding more and more arguments to all functions, progress reporting is using a similar mechanism to how logging works - progress reporting function is set with the init_prog_reporting(prog_func) call where prog_func takes guint64 task_id, BDUtilsProgStatus status, guint8 completion, gchar *msg. A new task_id is generated for every action/change, status is one of STARTED, PROGRESS or FINISHED, completion is a number from 0 to 100 (integer completion percentage) and msg is an optional message meant to be shown to the user or logged. prog_func is called in the same thread from which the action/change was started (and where it will also finish as all functions are synchronous) so it's easy for the caller to create a mapping between task_id and the action being performed in case of multiple actions running in parallel (in multiple threads).

Better #includes

Plugins using the utils helper library used to #include its headers as #include <utils.h> which could have caused issues if more -I paths contained such file. A similar thing could happen with other header files from the libblockdev library itself. To prevent such issues, header files are now included as #include <blockdev/utils.h> (and similar) and the caller code is also expected to use the blockdev/ prefix in #includes instead of adding -I/usr/include/blockdev as their preprocessor flag.

Summary

After 17 months [3] a new major version of libblockdev is released. The new API is not backwards compatible with the old one, but the changes are very small and it will be trivial to adapt any existing code to them. Overall the API breakage is definitely worth the new features which couldn't have been added otherwise. And the API is expected to stay backwards compatible for the next year plus as long as possible. There will be functions added, maybe even some more plugins, but nothing from the API will be removed or changed in any incompatible way. Hopefully there's a great future for the library as it is now being more and more used not only by the blivet library, but also by the storaged daemon.

[1] Python GI overrides hide the differences and preserve the API
[2] where the number in square brackets is a task identifier
[3] libblockdev-1.0 was realeased on May 21, 2015
For anonymous comments click into the Start the discussion entry, fill in your name (or a nick) and check the I'd rather post as a guest checkbox. Anonymous comments with links might require approval by an administrator.