LibCXX overview

LibCXX Windows Library is built using the LibCXX library, a library of classes and templates based on reference-counted objects. Some existing familiarity with LibCXX will be helpful in understanding how to use LibCXXW's classes, but is not strictly necessary. A brief overview follows.

All LibCXXW classes and templates are defined in the x::w namespace.

References

It's important to understand the relationship between the various objects and classes. All classes and templates, like x::w::connection and x::w::screen are reference-counted objects, based on x::ref and x::ptr. x::w::connection, x::w::screen and others, are just reference handles, similar to std::shared_ptr.

The LibCXX Windows Library takes care of creating the actual, underlying objects, and when the last reference, last handle, to the underlying object goes out of scope, the underlying object gets destroyed. This includes both the explicit references, and the internal references the underlying objects have to each other.

Except as stated, the LibCXX Windows Library's internal references are generally as follows:

  • The LibCXX Windows Library does not maintain its own internal references to top level display elements, like x::w::main_window.

  • x::w::main_window holds a reference on its x::w::screen, which holds a refernece on its x::w::connection.

  • A container holds a reference to its layout manager, and the layout manager holds reference to all elements in the container.

A main window is a container. Typically, an application creates its main window, and stores its x::w::main_window somewhere. The application procedes and creates the various display elements, putting them in their containers, which now hold a reference on them.

In this manner, all references end up being rooted in their main window object. When the application destroys its x::w::main_window handle, the cascading effect from that destroys all display elements and internal objects.

This works correctly as long as no other references to any display elements, or other related objects, exist. If the application has a reference to a display element, or some other LibCXX Windows Library object that's tied to the main application window, directly, or indirectly, this is going to prevent the main application window from getting properly destroyed.

The connection thread

As mentioned briefly in the introduction, the LibCXX Windows Library uses a separate thread for the connection with the display server. LibCXX Windows Library takes care of starting the connection thread. The connection thread gets automatically stopped when the last top level window gets destroyed.

The connection thread takes care of updating the display, and processing internal display protocol messages. The connection thread may also end up executing an application-supplied callback in the form of a lambda or some other callable object.

The connection thread resumes its normal duties after the application callback returns. Application callbacks should not get bogged down with long-running tasks, as this will result in the application window appearing to be frozen. Callbacks should be minimal, and consist of little more than sending a message of some kind, or setting a flag.

Different callbacks get installed or uninstalled in different ways. Due to asynchronous nature of the connection thread, the application must be prepared for the callback to be executing at the same time the application requests the callback to be turned off or uninstalled; or shortly thereafter before the callback's deactivation gets finalized.

As such, application's callbacks should safely capture anything they need by value (subject to restrictions on creating circular references). LibCXX's reference-counted objects (which are, incidentally, are used to build the LibCXX Windows Library itself) are an excellent suggestion. The callback and the main application coordinate their mutual dependency through some refernece-counted object. After both the application gets rid of its reference, and the callback gets uninstalled, with the captured reference going out of scope and getting destroyed, the underlying reference-counted object which was used for this coordination gets destroyed automatically.