 |
libghostty
|
|
libghostty
|
#include <ghostty/vt/terminal.h>
Data Fields | |
| size_t | size |
| bool | compression_supported |
| uint64_t | primary_pages |
| uint64_t | primary_virtual_bytes |
| uint64_t | primary_resident_bytes |
| uint64_t | primary_compressed_pages |
| uint64_t | primary_compressed_bytes |
| uint64_t | primary_image_bytes |
| uint64_t | alternate_pages |
| uint64_t | alternate_virtual_bytes |
| uint64_t | alternate_resident_bytes |
| uint64_t | alternate_compressed_pages |
| uint64_t | alternate_compressed_bytes |
| uint64_t | alternate_image_bytes |
Memory held by a terminal.
Read with ghostty_terminal_get() and GHOSTTY_TERMINAL_DATA_MEMORY_USAGE. This helps applications that host many terminals stay within a memory budget, for example by compressing or closing the terminals that hold the most memory first.
Most of a terminal's memory goes to its screen contents and scrollback, which are stored in fixed-size blocks called pages. Resident bytes are the physical memory pages use right now, and are the figure to budget against. Virtual bytes are the address space reserved for pages. Compressing scrollback lowers the resident figure but not the virtual one, because each page's space stays reserved for decompression.
This is a sized struct. Set size before the call, most easily with GHOSTTY_INIT_SIZED(). Later versions of libghostty-vt may add fields to the end of this struct, and the size tells the library which version your program was compiled against. This lets older programs keep working with newer versions of the library.
Each screen has its own set of fields, named with a primary_ or alternate_ prefix. The primary screen holds shell output and all of the scrollback. The alternate screen is used by full-screen programs such as text editors, and its fields are all zero until a program first switches to it. Add the two sets together for the terminal's total.
Everything the terminal displays is stored inside pages, including colors, styles and hyperlinks, so those are already part of the page figures. Images are stored separately and have their own fields. Small structures outside of pages, such as the window title and internal bookkeeping, are not counted. They are small next to the pages once a terminal has any scrollback.
On macOS, the operating system takes back memory freed by compression lazily, when something else needs it. Until then, the memory use the system reports for your process (its RSS) can be higher than the resident figures here.
Definition at line 462 of file terminal.h.
| uint64_t alternate_compressed_bytes |
The same as primary_compressed_bytes, for the alternate screen.
Definition at line 521 of file terminal.h.
| uint64_t alternate_compressed_pages |
The same as primary_compressed_pages, for the alternate screen.
Definition at line 518 of file terminal.h.
| uint64_t alternate_image_bytes |
The same as primary_image_bytes, for the alternate screen.
Definition at line 524 of file terminal.h.
| uint64_t alternate_pages |
The same as primary_pages, for the alternate screen.
Definition at line 509 of file terminal.h.
| uint64_t alternate_resident_bytes |
The same as primary_resident_bytes, for the alternate screen.
Definition at line 515 of file terminal.h.
| uint64_t alternate_virtual_bytes |
The same as primary_virtual_bytes, for the alternate screen.
Definition at line 512 of file terminal.h.
| bool compression_supported |
Whether compressing scrollback can free memory on this platform. When false, ghostty_terminal_compress() reports GHOSTTY_TERMINAL_COMPRESSION_RESULT_UNSUPPORTED and the compressed fields are always zero. To reduce a terminal's memory on such a platform, you have to do something else, such as closing it.
Definition at line 473 of file terminal.h.
| uint64_t primary_compressed_bytes |
Bytes of compressed data held for the primary screen's compressed pages. This is already included in primary_resident_bytes.
Definition at line 499 of file terminal.h.
| uint64_t primary_compressed_pages |
Number of the primary screen's pages that are compressed.
Definition at line 493 of file terminal.h.
| uint64_t primary_image_bytes |
Bytes of image data stored for the primary screen through the Kitty graphics protocol. This is not included in primary_resident_bytes. Always zero when libghostty-vt is built without Kitty graphics.
Definition at line 506 of file terminal.h.
| uint64_t primary_pages |
Number of pages in the primary screen, including compressed pages.
Definition at line 476 of file terminal.h.
| uint64_t primary_resident_bytes |
Bytes of physical memory used by the primary screen's pages. A compressed page counts only its compressed size. Use this figure for memory budgets.
Definition at line 490 of file terminal.h.
| uint64_t primary_virtual_bytes |
Bytes of address space reserved for the primary screen's pages. This includes compressed pages and spare pages kept ready for reuse. Always at least primary_resident_bytes.
Definition at line 483 of file terminal.h.
| size_t size |
Size of this struct in bytes. Set by the caller.
Definition at line 464 of file terminal.h.
1.18.0