Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
X11::Protocol::Ext::X_UseruContributed Perl DX11::Protocol::Ext::X_Resource(3)

       X11::Protocol::Ext::X_Resource -	server resource	usage

	use X11::Protocol;
	my $X =	X11::Protocol->new;
	  or print "X-Resource extension not available";

	my @clients = $X->XResourceQueryClients();

	my %resources =	$X->XResourceQueryClientResources ($client_xid);

	my $bytes = $X->XResourceQueryClientPixmapBytes	($client_xid);

       The X-Resource extension	gives some server resource utilization
       information, mainly for use as diagnostics.

       o   Current client connections and their	XID ranges.

       o   How many windows, pixmaps, GCs, etc in use by a given client.

       o   Total memory	used by	all the	pixmaps	of a given client.

       "Resources" here	means memory, objects, etc, not	to be confused with
       the resource database of	user preferences and widget settings of
       "RESOURCES" in X(7).

       See examples/ for a simple dump of the	resources

       The following requests are made available with an "init_extension()",
       as per "EXTENSIONS" in X11::Protocol.

	   my $is_available = $X->init_extension('X-Resource');

       "($server_major,	$server_minor) = $X->XResourceQueryVersion
       ($client_major, $client_minor)"
	   Negotiate the extension version.  $client_major and $client_minor
	   is what the client would like, the returned $server_major and
	   $server_minor is what the server will do, which might be lower than
	   requested (but not higher).

	   The current code supports X-Resource	1.0.  The intention is for
	   this	module to automatically	negotiate in "$X->init_extension()"
	   if/when needed.

       "@clients = $X->XResourceQueryClients ()"
	   Return a list of client connections on the server.  Each returned
	   value is an arrayref	pair

	       [ $xid_base, $xid_mask ]

	   $xid_base (an integer) is the start of XIDs for the client.

	   $xid_mask (an integer) is a bit mask	for the	XIDs above that	base
	   which the client may	use.  For example $xid_base might be 0xA00000
	   and $xid_mask 0x1FFFFF, meaning 0xA00000 through 0xBFFFFF is	this

	       my @clients = $X->XResourceQueryClients;
	       print "there are	",scalar(@clients)," clients\n";
	       foreach my $aref	(@clients) {
		 my $xid_base =	$aref->[0];
		 my $xid_mask =	$aref->[1];
		 printf	"client	base %X	mask %X\n", $xid_base, $xid_mask;

	   The given $X	connection itself is included in the return.  Its base
	   and mask are	per "$X->{'resource_id_base'}" and

       "($atom,$count,...) = $X->XResourceQueryClientResources ($xid)"
	   Return a list of how	many of	various	server things are used by a
	   given client.

	   The client is identified by an $xid.	 It can	be anything in the
	   client's XID	range and doesn't have to be currently allocated or
	   created.  For example to enquire about the current client use

	   The return is a list	of resource type (an atom integer) and count
	   of those things,

	       ($atom, $count, $atom, $count, ...)

	   So for example to print all resources,

	       my @res = $X->XResourceQueryClientResources ($xid);
	       while (@res) {
		 my $type_atom = shift @res;
		 my $count = shift @res;
		 my $type_name = $X->atom_name($type_atom);
		 printf	"type $type_name count $count\n";

	   Or put the list into	a hash to lookup a particular resource type,

	       my %res = $X->XResourceQueryClientResources ($xid);

	       my $window_atom = X11::AtomConstants::WINDOW();
	       my $windows = $res{$window_atom}	|| 0;

	       my $grab_atom = $X->atom('PASSIVE GRAB');
	       my $grabs = $res{$grab_atom} || 'no';

	       print "using $windows many windows, and $grabs passive grabs";

	   "List::Pairwise" has	"mapp()" and other things to work with this
	   sort	of two-at-a-time list.	See examples/ for
	   a complete program.

	   Generally a count entry is only present when	the client has 1 or
	   more	of the thing.  So if no	pixmaps	then no	"PIXMAP" entry at all.

	   Basics like "WINDOW", "PIXMAP", "GC"	"COLORMAP", "FONT" and
	   "CURSOR" are	how many of those in use.  The server might also
	   report things like "PASSIVEA	GRAB" or "COLORMAPA ENTRY" (atoms with
	   spaces in their names).  The server (circa version 1.9) even
	   sometimes reports things like "Unregistered resource	30" (an	atom
	   with	that name), which is something or other.

	   If the given	$xid is	not a connected	client then a "BadValue" error
	   results.  Be	careful	of that	when querying resources	of another
	   client since	the client might disconnect at any time.
	   "$X->robust_req()" is good, or maybe	"GrabServer" to	hold
	   connections between "XResourceQueryClients()" and

       "$bytes = $X->XResourceQueryClientPixmapBytes ($xid)"
	   Return the total bytes of memory on the server used by all the
	   pixmaps of a	given client.  Pixmaps which only exist	as window
	   backgrounds or GC tiles or stipples are included, or	should be.  If
	   the client has no pixmaps at	all the	return is 0.

	   The client is identified by an $xid as per
	   "XResourceQueryClientResources()" above.  It	can be anything	in the
	   client's XID	range, allocated or not.

	       my $pixmap = $X->new_rsrc;
	       $X->CreatePixmap	($pixmap,
				 100, 100);  # width,height

	       my $xid = $X->{'resource_id_base'};  # own usage
	       my $bytes = $X->XResourceQueryClientPixmapBytes ($xid);
	       print "total of all pixmaps is $bytes bytes of memory\n";

	   The return is a 64-bit value.  On a 32-bit Perl a bigger than 32
	   bits	is returned as floating	point, or bigger than 53 bit float as
	   "Math::BigInt".  Most of the	time 32	bits is	enough,	since that
	   would be 4 Gbytes of	pixmaps, and or	53-bit float should be plenty,
	   that	being about 8192 terabytes!

	   For reference, the server circa version 1.11.4	had a bug
	   where it didn't count space used by pixmaps of depth	less than 8
	   (including depth 1 bitmaps) in the bytes returned.

       X11::Protocol, X11::AtomConstants server source code



       Copyright 2011, 2012, 2013, 2014, 2017 Kevin Ryde

       X11-Protocol-Other is free software; you	can redistribute it and/or
       modify it under the terms of the	GNU General Public License as
       published by the	Free Software Foundation; either version 3, or (at
       your option) any	later version.

       X11-Protocol-Other is distributed in the	hope that it will be useful,
       but WITHOUT ANY WARRANTY; without even the implied warranty of
       General Public License for more details.

       You should have received	a copy of the GNU General Public License along
       with X11-Protocol-Other.	 If not, see <>.

perl v5.32.0			  2017-04-07 X11::Protocol::Ext::X_Resource(3)


Want to link to this manual page? Use this URL:

home | help