feat: add `fileBacked` and `purgeable` fields to `process.getSystemMemoryInfo()` for macOS #47628

cucbin · 2025-07-01T12:47:33Z

Description of Change

On macOS, the free value in the memory data obtained from process.getSystemMemoryInfo() differs significantly from the value displayed in Activity Monitor.

The reason is that the free value is calculated from free_count in vm_statistics64_data_t.

The relevant code is located in: https://source.chromium.org/chromium/chromium/src/+/main:base/process/process_metrics_apple.mm;drc=bcbe20a25707502c2ba340cfd4dbe8cd015fa864;l=255

To handle this issue, I propose two approaches:

Calculate and return the adjusted value directly in electron_bindings.cc while maintaining the original data format.
Add two new fields: cached and purgeable, to provide more granular memory usage details.

Checklist

PR description included and stakeholders cc'd
npm test passes
tests are changed or added
relevant API documentation, tutorials, and examples are updated and follow the documentation style guide
PR release notes describe the change in a way relevant to app developers, and are capitalized, punctuated, and past tense.

Release Notes

Notes: Added fileBacked and purgeable fields to process.getSystemMemoryInfo() for macOS.

MarshallOfSound

I'd prefer to expose new numbers, not change existing ones as people will have existing metrics that we'd be breaking.

Also cc @felixrieseberg because I know you've stared at how memory metrics work a lot in the past, any thoughts here

cucbin · 2025-07-02T13:24:17Z

@MarshallOfSound I agree with you. I have changed the code.
Thanks.

nikwen

Thanks! Could you please also adjust the docs?

electron/docs/api/process.md

Line 206 in 655037f

### `process.getSystemMemoryInfo()`

Could you please also update the PR title and release notes to reflect your most recent change?

cucbin · 2025-07-03T08:04:35Z

@nikwen
Thanks. Sure, I will complete the relevant API docs. Currently, I'm waiting to see the opinions of other members to determine whether additional data fields are needed or if these two fields are sufficient.

samuelmaddock · 2025-07-03T17:17:15Z

shell/common/api/electron_bindings.cc

@@ -183,8 +183,11 @@ v8::Local<v8::Value> ElectronBindings::GetSystemMemoryInfo(
 #endif
  dict.Set("free", free);

+#if BUILDFLAG(IS_MAC)
+  dict.Set("cached", mem_info.file_backed);


Should this be named fileBacked instead? I see another property named cached and want to make sure this won't conflict in the future.
https://source.chromium.org/chromium/chromium/src/+/main:base/process/process_metrics.h;l=365;drc=17b4c42cfb3512836655464b0d41d319e819c0b6

Yes, this field name might be better, I have considered using this name before.
Originally I wanted to make the name of this field consistent with what is displayed in the Activity Monitor.

itsananderson

A couple suggestions for tweaking the docs wording

docs/api/process.md

cucbin · 2025-07-11T13:59:01Z

@codebytere
could you please also review the changes?

codebytere

API LGTM

samuelmaddock

API LGTM

nikwen

Thanks for adding docs! The code looks fine to me.

Could you please update the release notes in the PR description?
Could you please use a more descriptive title for the PR? This will be the commit message once the PR is merged.

cucbin · 2025-07-18T13:18:56Z

@nikwen
Thanks for your suggestion.

nikwen · 2025-07-18T13:55:01Z

Thanks for the changes!

Please take a look at the commit message guidelines. The "add" in the PR title should be present tense and lowercase.

Additionally, it's always great to wrap any function or field names in backticks to render them as code, e.g.,fileBacked. This applies to both the PR title and the release notes.

cucbin · 2025-07-18T16:14:55Z

Thanks.
After searching the historical commit records, I found that there were many cases where "Added" was used, so I decided to use "Added".
I will pay attention to these rules when submitting PR next time.

nikwen · 2025-07-18T23:16:48Z

Thanks! We use present tense and lowercase for commit messages ("add"). We use past tense and capitalized for release notes ("Added").

itsananderson

API LGTM

…mMemoryInfo().

…yInfo().

Co-authored-by: Will Anderson <will@itsananderson.com>

cucbin · 2025-07-28T08:30:41Z

@codebytere
I rebase the code, please help me to trigger the check jobs. If it is all well, please help me merge it.
Thanks.

electron-cation bot added the new-pr 🌱 PR opened recently label Jul 1, 2025

MarshallOfSound requested changes Jul 1, 2025

View reviewed changes

cucbin changed the title ~~fix: Optimize the value of memory.free in the return data of getSystemMemoryInfo()~~ fix: Optimize the value of memory in the return data of getSystemMemoryInfo() Jul 2, 2025

cucbin changed the title ~~fix: Optimize the value of memory in the return data of getSystemMemoryInfo()~~ fix: Improve the value of memory in the return data of getSystemMemoryInfo() Jul 2, 2025

nikwen requested changes Jul 2, 2025

View reviewed changes

nikwen changed the title ~~fix: Improve the value of memory in the return data of getSystemMemoryInfo()~~ fix: improve the value of memory in the return data of getSystemMemoryInfo() Jul 2, 2025

nikwen changed the title ~~fix: improve the value of memory in the return data of getSystemMemoryInfo()~~ feat: improve the value of memory in the return data of getSystemMemoryInfo() Jul 3, 2025

nikwen added the api-review/requested 🗳 label Jul 3, 2025

samuelmaddock reviewed Jul 3, 2025

View reviewed changes

itsananderson reviewed Jul 3, 2025

View reviewed changes

docs/api/process.md Outdated Show resolved Hide resolved

cucbin force-pushed the fix/correct_mem_free_value_in_get_system_mem_info branch from b28f1be to 37ef641 Compare July 4, 2025 16:24

electron-cation bot removed the new-pr 🌱 PR opened recently label Jul 8, 2025

cucbin requested review from itsananderson, MarshallOfSound, samuelmaddock and nikwen July 9, 2025 01:37

codebytere approved these changes Jul 13, 2025

View reviewed changes

MarshallOfSound approved these changes Jul 17, 2025

View reviewed changes

samuelmaddock approved these changes Jul 17, 2025

View reviewed changes

nikwen requested changes Jul 17, 2025

View reviewed changes

cucbin changed the title ~~feat: improve the value of memory in the return data of getSystemMemoryInfo()~~ feat: Added fileBacked and purgeable fields to getSystemMemoryInfo() for macOS. Jul 18, 2025

cucbin changed the title ~~feat: Added fileBacked and purgeable fields to getSystemMemoryInfo() for macOS.~~ feat: Added fileBacked and purgeable fields to getSystemMemoryInfo() for macOS Jul 18, 2025

cucbin requested a review from nikwen July 18, 2025 13:17

cucbin changed the title ~~feat: Added fileBacked and purgeable fields to getSystemMemoryInfo() for macOS~~ feat: Added fileBacked and purgeable fields to process.getSystemMemoryInfo() for macOS Jul 18, 2025

codebytere changed the title ~~feat: Added fileBacked and purgeable fields to process.getSystemMemoryInfo() for macOS~~ feat: add fileBacked and purgeable fields to process.getSystemMemoryInfo() for macOS Jul 18, 2025

codebytere changed the title ~~feat: add fileBacked and purgeable fields to process.getSystemMemoryInfo() for macOS~~ feat: add fileBacked and purgeable fields to process.getSystemMemoryInfo() for macOS Jul 18, 2025

nikwen approved these changes Jul 18, 2025

View reviewed changes

itsananderson approved these changes Jul 24, 2025

View reviewed changes

cucbin and others added 5 commits July 28, 2025 16:28

fix: Optimize the value of memory.free in the return data of getSyste…

0fe777a

…mMemoryInfo().

fix: Improve the value of memory in the return data of getSystemMemor…

c541ab2

…yInfo().

fix: complete API doc.

b0bed38

Update docs/api/process.md

d7bab0f

Co-authored-by: Will Anderson <will@itsananderson.com>

fix: update name to fileBacked.

7e9faab

cucbin force-pushed the fix/correct_mem_free_value_in_get_system_mem_info branch from 37ef641 to 7e9faab Compare July 28, 2025 08:29

codebytere added semver/minor backwards-compatible functionality target/37-x-y PR should also be added to the "37-x-y" branch. target/38-x-y PR should also be added to the "38-x-y" branch. labels Aug 1, 2025

electron-cation bot added api-review/approved ✅ and removed api-review/requested 🗳 labels Aug 1, 2025

feat: add fileBacked and purgeable fields to process.getSystemMemoryInfo() for macOS #47628

Are you sure you want to change the base?

feat: add fileBacked and purgeable fields to process.getSystemMemoryInfo() for macOS #47628

Uh oh!

Conversation

cucbin commented Jul 1, 2025 • edited by nikwen Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description of Change

Checklist

Release Notes

Uh oh!

MarshallOfSound left a comment

Choose a reason for hiding this comment

Uh oh!

cucbin commented Jul 2, 2025

Uh oh!

nikwen left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cucbin commented Jul 3, 2025

Uh oh!

samuelmaddock Jul 3, 2025

Choose a reason for hiding this comment

Uh oh!

cucbin Jul 4, 2025

Choose a reason for hiding this comment

Uh oh!

itsananderson left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cucbin commented Jul 11, 2025

Uh oh!

codebytere left a comment

Choose a reason for hiding this comment

Uh oh!

samuelmaddock left a comment

Choose a reason for hiding this comment

Uh oh!

nikwen left a comment

Choose a reason for hiding this comment

Uh oh!

cucbin commented Jul 18, 2025

Uh oh!

nikwen commented Jul 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cucbin commented Jul 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nikwen commented Jul 18, 2025

Uh oh!

itsananderson left a comment

Choose a reason for hiding this comment

Uh oh!

cucbin commented Jul 28, 2025

Uh oh!

Uh oh!

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

feat: add `fileBacked` and `purgeable` fields to `process.getSystemMemoryInfo()` for macOS #47628

feat: add `fileBacked` and `purgeable` fields to `process.getSystemMemoryInfo()` for macOS #47628

cucbin commented Jul 1, 2025 •

edited by nikwen

Loading

nikwen left a comment •

edited

Loading

nikwen commented Jul 18, 2025 •

edited

Loading

cucbin commented Jul 18, 2025 •

edited

Loading