Skip to content

Commit 27be126

Browse files
anarazelanarazel
committed
aio: Add pg_aios view
The new view lists all IO handles that are currently in use and is mainly useful for PG developers, but may also be useful when tuning PG. FIXME: - catversion bump before commit Reviewed-by: Noah Misch <noah@leadboat.com> Discussion: https://postgr.es/m/uvrtrknj4kdytuboidbhwclo4gxhswwcpgadptsjvjqcluzmah%40brqs62irg4dt
1 parent f08dbe3 commit 27be126

File tree

9 files changed

+580
-0
lines changed

9 files changed

+580
-0
lines changed

‎doc/src/sgml/system-views.sgml

Lines changed: 294 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,11 @@
5151
</thead>
5252

5353
<tbody>
54+
<row>
55+
<entry><link linkend="view-pg-aios"><structname>pg_aios</structname></link></entry>
56+
<entry>In-use asynchronous IO handles</entry>
57+
</row>
58+
5459
<row>
5560
<entry><link linkend="view-pg-available-extensions"><structname>pg_available_extensions</structname></link></entry>
5661
<entry>available extensions</entry>
@@ -231,6 +236,295 @@
231236
</table>
232237
</sect1>
233238

239+
<sect1 id="view-pg-aios">
240+
<title><structname>pg_aios</structname></title>
241+
242+
<indexterm zone="view-pg-aios">
243+
<primary>pg_aios</primary>
244+
</indexterm>
245+
246+
<para>
247+
The <structname>pg_aios</structname> view lists all <xref
248+
linkend="glossary-aio"/> handles that are currently in-use. An I/O handle
249+
is used to reference an I/O operation that is being prepared, executed or
250+
is in the process of completing. <structname>pg_aios</structname> contains
251+
one row for each I/O handle.
252+
</para>
253+
254+
<para>
255+
This view is mainly useful for developers of
256+
<productname>PostgreSQL</productname>, but may also be useful when tuning
257+
<productname>PostgreSQL</productname>.
258+
</para>
259+
260+
<table>
261+
<title><structname>pg_aios</structname> Columns</title>
262+
<tgroup cols="1">
263+
<thead>
264+
<row>
265+
<entry role="catalog_table_entry"><para role="column_definition">
266+
Column Type
267+
</para>
268+
<para>
269+
Description
270+
</para></entry>
271+
</row>
272+
</thead>
273+
274+
<tbody>
275+
<row>
276+
<entry role="catalog_table_entry"><para role="column_definition">
277+
<structfield>pid</structfield> <type>int4</type>
278+
</para>
279+
<para>
280+
Process ID of the server process that is issuing this I/O.
281+
</para></entry>
282+
</row>
283+
284+
<row>
285+
<entry role="catalog_table_entry"><para role="column_definition">
286+
<structfield>io_id</structfield> <type>int4</type>
287+
</para>
288+
<para>
289+
Identifier of the I/O handle. Handles are reused once the I/O
290+
completed (or if the handle is released before I/O is started). On reuse
291+
<link linkend="view-pg-aios-io-generation">
292+
<structname>pg_aios</structname>.<structfield>io_generation</structfield>
293+
</link>
294+
is incremented.
295+
</para></entry>
296+
</row>
297+
298+
<row>
299+
<entry role="catalog_table_entry" id="view-pg-aios-io-generation"><para role="column_definition">
300+
<structfield>io_generation</structfield> <type>int8</type>
301+
</para>
302+
<para>
303+
Generation of the I/O handle.
304+
</para></entry>
305+
</row>
306+
307+
<row>
308+
<entry role="catalog_table_entry"><para role="column_definition">
309+
<structfield>state</structfield> <type>text</type>
310+
</para>
311+
<para>
312+
State of the I/O handle:
313+
<itemizedlist>
314+
<listitem>
315+
<para>
316+
<literal>HANDED_OUT</literal>, referenced by code but not yet used
317+
</para>
318+
</listitem>
319+
<listitem>
320+
<para>
321+
<literal>DEFINED</literal>, information necessary for execution is known
322+
</para>
323+
</listitem>
324+
<listitem>
325+
<para>
326+
<literal>STAGED</literal>, ready for execution
327+
</para>
328+
</listitem>
329+
<listitem>
330+
<para>
331+
<literal>SUBMITTED</literal>, submitted for execution
332+
</para>
333+
</listitem>
334+
<listitem>
335+
<para>
336+
<literal>COMPLETED_IO</literal>, finished, but result has not yet been processed
337+
</para>
338+
</listitem>
339+
<listitem>
340+
<para>
341+
<literal>COMPLETED_SHARED</literal>, shared completion processing completed
342+
</para>
343+
</listitem>
344+
<listitem>
345+
<para>
346+
<literal>COMPLETED_LOCAL</literal>, backend local completion processing completed
347+
</para>
348+
</listitem>
349+
</itemizedlist>
350+
</para></entry>
351+
</row>
352+
353+
<row>
354+
<entry role="catalog_table_entry"><para role="column_definition">
355+
<structfield>operation</structfield> <type>text</type>
356+
</para>
357+
<para>
358+
Operation performed using the I/O handle:
359+
<itemizedlist>
360+
<listitem>
361+
<para>
362+
<literal>invalid</literal>, not yet known
363+
</para>
364+
</listitem>
365+
<listitem>
366+
<para>
367+
<literal>readv</literal>, a vectored read
368+
</para>
369+
</listitem>
370+
<listitem>
371+
<para>
372+
<literal>writev</literal>, a vectored write
373+
</para>
374+
</listitem>
375+
</itemizedlist>
376+
</para></entry>
377+
</row>
378+
379+
<row>
380+
<entry role="catalog_table_entry"><para role="column_definition">
381+
<structfield>off</structfield> <type>int8</type>
382+
</para>
383+
<para>
384+
Offset of the I/O operation.
385+
</para></entry>
386+
</row>
387+
388+
<row>
389+
<entry role="catalog_table_entry"><para role="column_definition">
390+
<structfield>length</structfield> <type>int8</type>
391+
</para>
392+
<para>
393+
Length of the I/O operation.
394+
</para></entry>
395+
</row>
396+
397+
<row>
398+
<entry role="catalog_table_entry"><para role="column_definition">
399+
<structfield>target</structfield> <type>text</type>
400+
</para>
401+
<para>
402+
What kind of object is the I/O targeting:
403+
<itemizedlist spacing="compact">
404+
<listitem>
405+
<para>
406+
<literal>smgr</literal>, I/O on relations
407+
</para>
408+
</listitem>
409+
</itemizedlist>
410+
</para></entry>
411+
</row>
412+
413+
<row>
414+
<entry role="catalog_table_entry"><para role="column_definition">
415+
<structfield>handle_data_len</structfield> <type>int2</type>
416+
</para>
417+
<para>
418+
Length of the data associated with the I/O operation. For I/O to/from
419+
<xref linkend="guc-shared-buffers"/> and <xref
420+
linkend="guc-temp-buffers"/>, this indicates the number of buffers the
421+
I/O is operating on.
422+
</para></entry>
423+
</row>
424+
425+
<row>
426+
<entry role="catalog_table_entry"><para role="column_definition">
427+
<structfield>raw_result</structfield> <type>int4</type>
428+
</para>
429+
<para>
430+
Low-level result of the I/O operation, or NULL if the operation has not
431+
yet completed.
432+
</para></entry>
433+
</row>
434+
435+
<row>
436+
<entry role="catalog_table_entry"><para role="column_definition">
437+
<structfield>result</structfield> <type>text</type>
438+
</para>
439+
<para>
440+
High-level result of the I/O operation:
441+
<itemizedlist>
442+
<listitem>
443+
<para>
444+
<literal>UNKNOWN</literal> means that the result of the
445+
operation is not yet known.
446+
</para>
447+
</listitem>
448+
<listitem>
449+
<para>
450+
<literal>OK</literal> means the I/O completed successfully.
451+
</para>
452+
</listitem>
453+
<listitem>
454+
<para>
455+
<literal>PARTIAL</literal> means that the I/O completed without
456+
error, but did not process all data. Commonly callers will need to
457+
retry and perform the remainder of the work in a separate I/O.
458+
</para>
459+
</listitem>
460+
<listitem>
461+
<para>
462+
<literal>WARNING</literal> means that the I/O completed without
463+
error, but that execution of the IO triggered a warning. E.g. when
464+
encountering a corrupted buffer with <xref
465+
linkend="guc-zero-damaged-pages"/> enabled.
466+
</para>
467+
</listitem>
468+
<listitem>
469+
<para>
470+
<literal>ERROR</literal> means the I/O failed with an error.
471+
</para>
472+
</listitem>
473+
</itemizedlist>
474+
</para></entry>
475+
</row>
476+
477+
<row>
478+
<entry role="catalog_table_entry"><para role="column_definition">
479+
<structfield>target_desc</structfield> <type>text</type>
480+
</para>
481+
<para>
482+
Description of what the I/O operation is targeting.
483+
</para></entry>
484+
</row>
485+
486+
<row>
487+
<entry role="catalog_table_entry"><para role="column_definition">
488+
<structfield>f_sync</structfield> <type>bool</type>
489+
</para>
490+
<para>
491+
Flag indicating whether the I/O is executed synchronously.
492+
</para></entry>
493+
</row>
494+
495+
<row>
496+
<entry role="catalog_table_entry"><para role="column_definition">
497+
<structfield>f_localmem</structfield> <type>bool</type>
498+
</para>
499+
<para>
500+
Flag indicating whether the I/O references process local memory.
501+
</para></entry>
502+
</row>
503+
504+
<row>
505+
<entry role="catalog_table_entry"><para role="column_definition">
506+
<structfield>f_buffered</structfield> <type>bool</type>
507+
</para>
508+
<para>
509+
Flag indicating whether the I/O is buffered I/O.
510+
</para></entry>
511+
</row>
512+
513+
</tbody>
514+
</tgroup>
515+
</table>
516+
517+
<para>
518+
The <structname>pg_aios</structname> view is read-only.
519+
</para>
520+
521+
<para>
522+
By default, the <structname>pg_aios</structname> view can be read only by
523+
superusers or roles with privileges of the
524+
<literal>pg_read_all_stats</literal> role.
525+
</para>
526+
</sect1>
527+
234528
<sect1 id="view-pg-available-extensions">
235529
<title><structname>pg_available_extensions</structname></title>
236530

‎src/backend/catalog/system_views.sql

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1391,3 +1391,10 @@ CREATE VIEW pg_stat_subscription_stats AS
13911391

13921392
CREATE VIEW pg_wait_events AS
13931393
SELECT * FROM pg_get_wait_events();
1394+
1395+
CREATE VIEW pg_aios AS
1396+
SELECT * FROM pg_get_aios();
1397+
REVOKE ALL ON pg_aios FROM PUBLIC;
1398+
GRANT SELECT ON pg_aios TO pg_read_all_stats;
1399+
REVOKE EXECUTE ON FUNCTION pg_get_aios() FROM PUBLIC;
1400+
GRANT EXECUTE ON FUNCTION pg_get_aios() TO pg_read_all_stats;

‎src/backend/storage/aio/Makefile

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ include $(top_builddir)/src/Makefile.global
1111
OBJS = \
1212
aio.o \
1313
aio_callback.o \
14+
aio_funcs.o \
1415
aio_init.o \
1516
aio_io.o \
1617
aio_target.o \

0 commit comments

Comments
 (0)