Chapter 29. Connections and screens

Index

Connection mcguffins
#include <x/w/connection.H>
#include <x/w/screen.H>

x::w::screen s=x::w::screen::create();

x::w::connection conn=x::w::connection::create();

x::w::connection conn=x::w::connection::create("localhost:0.0");

size_t n=conn->screens();

size_t n=conn->default_screen();

x::w::screen s=x::w::screen::create(conn, 0);
      

An x::w::screen represents a screen on the display server. The default constructor returns the default screen on the default display server. An explicit x::w::connection represents an explicit connection to the display server, either a default display server, or an explicitly specified one, and can be passed to x::w::screen's constructor to get the screen for the specified connection. x::w::connection's screens() gives the number of screens on the display. They are numbered starting with 0, and default_screen() gives the default screen's number.

A screen number can also be passed to x::w::screen's constructor to get a handle for a screen other than the default one.

Connection mcguffins

#include <x/w/connection.H>
#include <x/w/screen.H>
#include <x/destroy_callback.H>

x:ref<x::obj> application()
{
     auto conn=x::w::connection::create();


     // ...

     return conn->mcguffin();
}

int main()
{
   try {
	x::destroy_callback::base::guard guard;

	guard( application() );
   } catch (const x::exception &e)
   {
       e->caught();
   }
}

As described in the section called “Introduction”, LibCXX Windows Library's objects are reference-counted objects that get automatically destroyed when the last reference to the objects go out of scope. However, there are other references to internal objects maintained by the library's internal execution thread. This abbreviated example destroys all objects when application() returns; however a library execution thread could still be running for a brief interval of time before it stops, and the connection to the display server is properly closed.

A connection object's mcguffin() method returns a LibCXX mcguffin that gets destroyed only after every internal library resource is released, and the connection to the display server gets closed.

Note that the mcguffin will exist if the screen or the connection object still exists, that's why this example returns just the mcguffin from application(), and the screen and connection objects in the application() get destroyed, but the mcguffin survives in main(). This example uses LibCXX's guard object to wait until the mcguffin gets destroyed. Now, everything is truly cleaned up.

Another subtle detail: the mcguffin only gets guarded if application() returns normally. The mcguffin does not get returned, and guarded, when an exception gets thrown. Presumably, a thrown exception indicates that the application reached an abnormal state, and orderly unwinding and destruction of all reference-counted objects may not have taken place. Any dangling reference to some LibCXXW object, somewhere, will likely prevent the mcguffin from getting destroyed. Instead, when main() returns, LibCXX is going to wait a moderate amount of time for all execution threads to stop, and bail out with a complaint in the worst case.