X11::Protocol::Ext::X_Resource(3pm)

1X11::Protocol::Ext::X_RUesseorurCcoen(t3r)ibuted Perl DoXc1u1m:e:nPtraottioocnol::Ext::X_Resource(3)
2
3
4

NAME

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

SYNOPSIS

9        use X11::Protocol;
10        my $X = X11::Protocol->new;
11        $X->init_extension('X-Resource')
12          or print "X-Resource extension not available";
13
14        my @clients = $X->XResourceQueryClients();
15
16        my %resources = $X->XResourceQueryClientResources ($client_xid);
17
18        my $bytes = $X->XResourceQueryClientPixmapBytes ($client_xid);
19

DESCRIPTION

21       The X-Resource extension gives some server resource utilization
22       information, mainly for use as diagnostics.
23
24       •   Current client connections and their XID ranges.
25
26       •   How many windows, pixmaps, GCs, etc in use by a given client.
27
28       •   Total memory used by all the pixmaps of a given client.
29
30       "Resources" here means memory, objects, etc, not to be confused with
31       the resource database of user preferences and widget settings of
32       "RESOURCES" in X(7).
33
34       See examples/xresource-print.pl for a simple dump of the resources
35       reported.
36

REQUESTS

38       The following requests are made available with an init_extension(), as
39       per "EXTENSIONS" in X11::Protocol.
40
41           my $is_available = $X->init_extension('X-Resource');
42
43       "($server_major, $server_minor) = $X->XResourceQueryVersion
44       ($client_major, $client_minor)"
45           Negotiate the extension version.  $client_major and $client_minor
46           is what the client would like, the returned $server_major and
47           $server_minor is what the server will do, which might be lower than
48           requested (but not higher).
49
50           The current code supports X-Resource 1.0.  The intention is for
51           this module to automatically negotiate in "$X->init_extension()"
52           if/when needed.
53
54       "@clients = $X->XResourceQueryClients ()"
55           Return a list of client connections on the server.  Each returned
56           value is an arrayref pair
57
58               [ $xid_base, $xid_mask ]
59
60           $xid_base (an integer) is the start of XIDs for the client.
61
62           $xid_mask (an integer) is a bit mask for the XIDs above that base
63           which the client may use.  For example $xid_base might be 0xA00000
64           and $xid_mask 0x1FFFFF, meaning 0xA00000 through 0xBFFFFF is this
65           client.
66
67               my @clients = $X->XResourceQueryClients;
68               print "there are ",scalar(@clients)," clients\n";
69               foreach my $aref (@clients) {
70                 my $xid_base = $aref->[0];
71                 my $xid_mask = $aref->[1];
72                 printf "client base %X mask %X\n", $xid_base, $xid_mask;
73               }
74
75           The given $X connection itself is included in the return.  Its base
76           and mask are per "$X->{'resource_id_base'}" and
77           "$X->{'resource_id_mask'}".
78
79       "($atom,$count,...) = $X->XResourceQueryClientResources ($xid)"
80           Return a list of how many of various server things are used by a
81           given client.
82
83           The client is identified by an $xid.  It can be anything in the
84           client's XID range and doesn't have to be currently allocated or
85           created.  For example to enquire about the current client use
86           "$X->{'resource_id_base'}".
87
88           The return is a list of resource type (an atom integer) and count
89           of those things,
90
91               ($atom, $count, $atom, $count, ...)
92
93           So for example to print all resources,
94
95               my @res = $X->XResourceQueryClientResources ($xid);
96               while (@res) {
97                 my $type_atom = shift @res;
98                 my $count = shift @res;
99                 my $type_name = $X->atom_name($type_atom);
100                 printf "type $type_name count $count\n";
101               }
102
103           Or put the list into a hash to lookup a particular resource type,
104
105               my %res = $X->XResourceQueryClientResources ($xid);
106
107               my $window_atom = X11::AtomConstants::WINDOW();
108               my $windows = $res{$window_atom} || 0;
109
110               my $grab_atom = $X->atom('PASSIVE GRAB');
111               my $grabs = $res{$grab_atom} || 'no';
112
113               print "using $windows many windows, and $grabs passive grabs";
114
115           "List::Pairwise" has mapp() and other things to work with this sort
116           of two-at-a-time list.  See examples/xresource-pairwise.pl for a
117           complete program.
118
119           Generally a count entry is only present when the client has 1 or
120           more of the thing.  So if no pixmaps then no "PIXMAP" entry at all.
121
122           Basics like "WINDOW", "PIXMAP", "GC" "COLORMAP", "FONT" and
123           "CURSOR" are how many of those in use.  The server might also
124           report things like "PASSIVE GRAB" or "COLORMAP ENTRY" (atoms with
125           spaces in their names).  The X.org server (circa version 1.9) even
126           sometimes reports things like "Unregistered resource 30" (an atom
127           with that name), which is something or other.
128
129           If the given $xid is not a connected client then a "BadValue" error
130           results.  Be careful of that when querying resources of another
131           client since the client might disconnect at any time.
132           "$X->robust_req()" is good, or maybe "GrabServer" to hold
133           connections between XResourceQueryClients() and
134           XResourceQueryClientResources().
135
136       "$bytes = $X->XResourceQueryClientPixmapBytes ($xid)"
137           Return the total bytes of memory on the server used by all the
138           pixmaps of a given client.  Pixmaps which only exist as window
139           backgrounds or GC tiles or stipples are included, or should be.  If
140           the client has no pixmaps at all the return is 0.
141
142           The client is identified by an $xid as per
143           XResourceQueryClientResources() above.  It can be anything in the
144           client's XID range, allocated or not.
145
146               my $pixmap = $X->new_rsrc;
147               $X->CreatePixmap ($pixmap,
148                                 $X->{'root'},
149                                 $X->{'root_depth'},
150                                 100, 100);  # width,height
151
152               my $xid = $X->{'resource_id_base'};  # own usage
153               my $bytes = $X->XResourceQueryClientPixmapBytes ($xid);
154               print "total of all pixmaps is $bytes bytes of memory\n";
155
156           The return is a 64-bit value.  On a 32-bit Perl a bigger than 32
157           bits is returned as floating point, or bigger than 53 bit float as
158           "Math::BigInt".  Most of the time 32 bits is enough, since that
159           would be 4 Gbytes of pixmaps, and or 53-bit float should be plenty,
160           that being about 8192 terabytes!
161
162           For reference, the X.org server circa version 1.11.4 had a bug
163           where it didn't count space used by pixmaps of depth less than 8
164           (including depth 1 bitmaps) in the bytes returned.
165

HOME PAGE

175       <http://user42.tuxfamily.org/x11-protocol-other/index.html>
176

LICENSE

178       Copyright 2011, 2012, 2013, 2014, 2017 Kevin Ryde
179
180       X11-Protocol-Other is free software; you can redistribute it and/or
181       modify it under the terms of the GNU General Public License as
182       published by the Free Software Foundation; either version 3, or (at
183       your option) any later version.
184
185       X11-Protocol-Other is distributed in the hope that it will be useful,
186       but WITHOUT ANY WARRANTY; without even the implied warranty of
187       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
188       General Public License for more details.
189
190       You should have received a copy of the GNU General Public License along
191       with X11-Protocol-Other.  If not, see <http://www.gnu.org/licenses/>.
192
193
194
195perl v5.36.0                      2023-01-20 X11::Protocol::Ext::X_Resource(3)

NAME

SYNOPSIS

DESCRIPTION

REQUESTS

SEE ALSO

HOME PAGE

LICENSE