Geek tip: g_object_new and constructors

tl;dr Don’t put any code in your foo_label_new() function other than g_object_new(), and watch out with Vala.

From this GJS bug report I realized there’s a trap that GObject library writers can fall into,

Avoid code at your construction site.

that I don’t think is documented anywhere. So I’m writing a blog post about it. I hope readers from Planet GNOME can help figure out where it needs to be documented.

For an object (let’s call it FooLabel) that’s part of the public API of a library (let’s call it libfoo), creating the object via its foo_label_new() constructor function should be equivalent to creating it via g_object_new().

If foo_label_new() takes no arguments then it should literally be only this:

FooLabel *
foo_label_new(void)
{
    return g_object_new(FOO_TYPE_LABEL, NULL);
}

If it does take arguments, then they should correspond to construct properties, and they should get set in the g_object_new() call. (It’s customary to at least put all construct-only properties as arguments to the constructor function.) For example:

FooLabel *
foo_label_new(const char *text)
{
    return g_object_new(FOO_TYPE_LABEL,
        "text", text,
        NULL);
}

Do not put any other code in foo_label_new(). That is, don’t do this:

FooLabel *
foo_label_new(void)
{
    FooLabel *retval = g_object_new(FOO_TYPE_LABEL, NULL);
    retval->priv->some_variable = 5;  /* Don't do this! */
    return retval;
}

The reason for that is because callers of your library will expect to be able to create FooLabels using g_object_new() in many situations. This is done when creating a FooLabel in JS and Python, but also when creating one from a Glade file, and also in plain old C when you need to set construct properties. In all those situations, the private field some_variable will not get initialized to 5!

Instead, put the code in foo_label_init(). That way, it will be executed regardless of how the object is constructed. And if you need to write code in the constructor that depends on construct properties that have been set, use the constructed virtual function. There’s a code example here.

If you want more details about what function is called when, Allison Lortie has a really useful blog post.

This trap can be easy to fall into in Vala. Using a construct block is the right way to do it:

namespace Foo {
public class Label : GLib.Object {
    private int some_variable;

    construct {
        some_variable = 5;
    }
}
}

This is the wrong way to do it:

namespace Foo {
public class Label : GLib.Object {
    private int some_variable;

    public Label() {
        some_variable = 5;  // Don't do this!
    }
}
}

This is tricky because the wrong way seems like the most obvious way to me!

This has been a public service announcement for the GNOME community, but here’s where you come in! Please help figure out where this should be documented, and whether it’s possible to enforce it through automated tools.

For example, the Writing Bindable APIs page seems like a good place to warn about it, and I’ve already added it there. But this should probably go into Vala documentation in the appropriate place. I have no idea if this is a problem with Rust’s gobject_gen! macro, but if it is then it should be documented as well.

Documented pitfalls are better than undocumented pitfalls, but removing the pitfall altogether is better. Is there a way we can check this automatically?

Javascript news from GNOME 3.24

Welcome back to the latest news on GJS, the Javascript engine that powers GNOME Shell, Endless OS, Polari, GNOME Documents, and many other apps.

GNOME 3.24 has been released for about three weeks now, and with it went GJS 1.48.0. Here’s what’s new!

Javascript upgrade!

First of all, we have a more modern Javascript engine. GJS is based on Mozilla’s SpiderMonkey, the same Javascript engine that runs in the Firefox browser. Back in GNOME 3.22, GJS was based on version 24, which was released in September 2013. Now we’ve moved to version 38, which although still old, was released almost two years later in May 2015.

(The number of each SpiderMonkey release increases by 7 each time, because they make a standalone SpiderMonkey release for each Extended Support Release of Firefox, which is one out of every 7. That’s why you might also hear them referred to as “ESR 38”, etc.)

This brings a lot of new Javascript language features with it. Here are some of the ones I’m most excited about.

Promises

Promises allow you to do asynchronous operations (like reading files, or waiting, or fetching things from the network) in a much more intuitive way. With Promises, the code reads from top to bottom as if it were synchronous, instead of from nested level to nested level (often called “callback hell“.)

Here’s an example, a Promises version of examples/gio-cat.js that’s included in GJS’s source distribution:

	const GLib = imports.gi.GLib;
	const Gio = imports.gi.Gio;
	function wrapPromise(obj, cancellable, asyncName, finishName, …inArgs) {
	return new Promise((resolve, reject) => {
	let callerStack = new Error().stack
	.split('\n')
	.filter(line => !line.match(/<Promise>|wrapPromise/))
	.join('\n');
	obj[asyncName](…inArgs, cancellable, (obj, res) => {
	try {
	let results = obj[finishName](res);
	resolve(results);
	} catch (e) {
	e.stack += '— Called from: —\n' + callerStack;
	reject(e);
	}
	});
	});
	}
	function loadContents(file, cancellable=null) {
	return wrapPromise(file, cancellable, 'load_contents_async',
	'load_contents_finish');
	}
	// ————————-
	let loop = GLib.MainLoop.new(null, false);
	function cat(filename) {
	let f = Gio.File.new_for_commandline_arg(filename);
	loadContents(f)
	.then(([ok, contents]) => {
	print(contents);
	})
	.catch(e => {
	logError(e);
	})
	.then(() => loop.quit());
	loop.run();
	}
	if (ARGV.length != 1) {
	printerr("Usage: gio-cat.js filename");
	} else {
	cat(ARGV[0]);
	}

view raw

gio-cat.js

hosted with ❤ by GitHub

This is much longer than the original program, but only the lower part of the program is actually the equivalent of the old callback-based code. The top part would ideally be provided by GJS itself. I’m still figuring out what is the best API for wrapPromise but it’s definitely a candidate for including in a future version of GJS.

This code calls loadContents, prints the contents, and exits the main loop. If an exception is thrown anywhere in the chain before .catch, then the function provided to the catch call will log the error message. In any case, no matter whether the operation succeeded or not, the last then call will make sure the main loop exits.

Template literals

Template literals will change your life if you work with text in your GJS program. They are regular strings in backticks, with interpolation. Say goodbye to this:

const Format = imports.format;
String.prototype.format = Format.format;
log("%s, %s!".format(greeting, name));

Also say goodbye to this:

log(greeting + ", " + name + "!");

Instead, from now on you’ll do this:

log(`${greeting}, ${name}!`);

It’s a lot more readable and intuitive.

Template literals can also cover more than one line, and they do real interpolation of expressions too, not just variable names:

const CSS = `
label {
    font-size: ${fontdesc.get_size()};
}`;

You can also “tag” templates which is out of scope of this blog post, but there is one built-in tag which serves the same purpose as r'' string literals do in Python:

String.raw`I'm writing some \LaTeX\ code here
and I \textbf{don't} want to deal with escaping it:
\[ E = mc^2 \]`

Generators

Generators are a great addition to the Javascript toolbox. They were actually already available in GJS, but only in Mozilla’s nonstandard extension form. They are introduced with the function* keyword instead of function, and they work a lot like Python’s generators. Here’s an example, implementing the xrange() function similar to the one in Python using a generator:

function* xrange(limit) {
    for(let count = 0; count < limit; count++)
        yield count;
}

The yield statement returns control back to the caller, while preserving the state of the generator until the next call. You can get all the values one by one, calling a generator’s next() method, but for...of loops will also deal with generators:

for (let ix of xrange(5))
    print(`Counting from 0 to 4: ${ix}`);

If you want to empty a generator into an array, you can also use the spread operator: [...xrange(5)] will give you an array of numbers from 0 to 4.

Here’s a more complicated example showing the yield* statement which allows you to compose more than one generator:

	const Gio = imports.gi.Gio;
	function* leafnodes(file) {
	let enumerator = file.enumerate_children('standard::*', 0, null);
	let info;
	while ((info = enumerator.next_file(null))) {
	let child = enumerator.get_child(info);
	if (info.get_file_type() === Gio.FileType.DIRECTORY)
	yield* leafnodes(child);
	else
	yield child.get_basename();
	}
	}
	let file = Gio.File.new_for_commandline_arg(ARGV[0]);
	for (let leaf of leafnodes(file))
	print(leaf);

view raw

leafnode.js

hosted with ❤ by GitHub

This code prints looks at the directory that it’s given, and prints all the files in it that are not themselves directories (the “leaf nodes”.) If one of the files is a directory, it will descend into that directory and repeat the process, thanks to yield*.

Want to know more?

Since there’s a lot more than I can cover in a comfortably readable blog post, I made a slide deck. I tried to put it together in such a way that you can use it as reference material.

For more information on all of these cool things, I highly recommend this “ES6 Explained” series of posts from the Mozilla Hacks blog. Some of these features, such as classes and modules, are still to come in GJS.

Maintainer life

The Javascript engine upgrade was the major feature, but I also spent some time on making things easier for myself as the maintainer. A well-tended garden will hopefully attract more gardeners. Happily, some other people joined in for this part.

I cleaned up the build system, using more modern and concise Autotools code. I also spent some time cleaning up compiler warnings, both on GCC and Clang. Now the build and test runs are faster, and the cleaner output makes it much easier to see when something goes wrong. I also made sure that GJS builds on macOS, or at least it did until my Apple hardware broke down. Chun-wei Fan made some improvements that ensure GJS builds on Windows with MSVC. Claudio André implemented continuous integration in a Docker container, with the intention to run it on Travis CI, but sadly we do not have permission to flip the bit to get Travis to build it.

Having written Jasmine GJS in order to bring some of that convenient unit testing technology from the Node world into GJS applications, I also wanted to use it for writing GJS’s own unit tests. I couldn’t use it directly because that would have been a circular dependency, of course, but I embedded a copy of upstream Jasmine plus a very stripped-down version of Jasmine GJS, and called it “Minijasmine”. It’s now a lot easier, and dare I say less of a drag, to write unit tests for GJS. Accordingly, we’ll now try to cover every bug fix with a regression test.

And I worked on getting the bug tracker down to a less daunting number of bugs. It was fun to make the bug chart in my last post, so here’s another one: this is the number of open bugs during the release cycle from 1.46.0 to 1.48.0.

You can definitely see that November Bug Squash Month had an effect

Unfortunately the chart will not look like this again next time around. The big drop was me closing all the obsolete or already-fixed bugs during November Bug Squash Month. We are down from about 160 to about 100 bugs, but those were all the easy ones; there are only hard ones left now.

Thanks

Thanks to everyone who participated to bring GJS to GNOME 3.24: Chun-wei Fan, Claudio André, Florian Müllner, Alexander Larsson, Iain Lane, Jonh Wendell, and Lionel Landwerlin.

As well, this release incorporated a lot of patches that people contributed a long time ago, even up to 8 years, that for various reasons had not been reviewed yet. (Many from emeritus GJS maintainers!) Thanks to those people for participating in the past, and I’m glad we were able to finally bring your contributions into the project: Giovanni Campagna, Jasper St. Pierre, Sam Spilsbury, Havoc Pennington, Joe Shaw, Paolo Borelli, Shawn Walker, and Tim Lunn.

Luke Jones and Hussam Al-Tayeb identified a serious memory leak right before the final 1.48.0 release and without their contribution, it would have been a different and much sadder story. As it was, 1.48.0 still contained another serious bug that made GNOME Shell quite unusable for an unlucky few people. Thanks to Georges Stavracas for rewriting a happy ending for 1.48.2.

Special thanks to Cosimo Cecchi, for reviewing almost every single line of the code I wrote for this release: about 20000 lines, many of them boring and repetitive.

Thanks also to my employer Endless which sponsored most of the Javascript engine upgrade, and a good chunk of miscellaneous bug fixing time.

Looking forward

My next post will be about what’s to come in GJS for GNOME 3.26.

Geek tip: Running Python GUIs in Sublime Text 2

I’m trying out Sublime Text 2 as a code editor on Windows, since there really aren’t any other free ones I like; unfortunately, my favorite free editor, Gedit, is abysmal on Windows. (Although it looks like something may be done about that soon.) Sublime works really well and has a distraction-free mode, and the extensibility is amazing. I’m not convinced yet that it’s worth $60 for a license — I’d probably pay $25, come on, it’s a text editor — but perhaps if I got a job where I needed text editors more often, I’d try to convince my boss to spring for it. (Although in that case, I’d more likely try to convince my boss to let me work on a platform where I could run Gedit.)

One thing that confused me is that I couldn’t get any of my Python GUI code to work on it. For example, when I’m at work in my lab, I often make small changes to my laser beam profiling program (although really it’s more of a camera driver right now; I haven’t found an excuse to actually write any Gaussian profiling code.) As far as I could figure out, I ought to be able to press Ctrl+B in Sublime Text to run the program. However, nothing ever happened, and I thought the feature must be broken.

Then one time I tried running another non-GUI Python script from Sublime Text. To my surprise, it worked! The feature apparently wasn’t really broken, just selective.

The key to this mystery was the following sentence from the Sublime Text 2 reference wiki:

On Windows, GUIs are suppressed.

Wait, what the what? Why would anybody want that? I guess so the console window doesn’t show up. Fortunately, it’s easy to remedy. Go to Preferences→Browse Packages, open the Default directory and then open exec.py in the editor. Around line 26, you’ll see:

# Hide the console window on Windows
startupinfo = None
if os.name == "nt":
    startupinfo = subprocess.STARTUPINFO()
    startupinfo.dwFlags |= subprocess.STARTF_USESHOWWINDOW

Comment out the last line of this block. Now, whenever you start a Python program, the console will be displayed. If you want to get rid of it, make your build system invoke pythonw instead of python. (Tools→Build System→New Build System, then copy Packages/Python/Python.sublime-build and change python to pythonw.)

Geek tip: ImagingSource camera in Python

In my lab there are some ImagingSource cameras that we use for detection. I was trying to get a model DMK 41BU02 to work so that I could control it directly from my measurement program and not have to use the crappy imaging software that comes with it.

Most USB cameras work with the OpenCV computer vision library without any trouble, and this is how I control them in my instrumentation library, which I wrote in Python. If they don’t work, then there is always an ActiveX interface which usually works.

The ImagingSource cameras, however, include their own driver library, IC Imaging Control. I tried to use SWIG to write a quick Python wrapper for it. However, you can only compile your program with this library if you use Visual C++. Fail!

Thankfully, this article (in German) on the blog of one Edgar Klenske tipped me off: the IC Imaging Control library is itself just a wrapper around DirectShow. That also explains why the headers only compile with VC++. Edgar Klenske’s solution is to use the VideoCapture module, which is itself a wrapper around DirectShow, which comes precompiled so you don’t have to use VC++. Luckily for me, he posted that tip just last week!

And so I was able to subclass my Camera module to interface with DirectShow cameras. Perhaps next I’ll try to install the new OpenCV 2.3 to see if their support for DirectShow has improved any.

My verdict is, never buy any camera from ImagingSource. Their slogan is, ironically, “Technology based on standards.” Sorry, but having your drivers only work with one compiler is more like a lack of standards — standards of both technology and decency.