feat: add `fileBacked` and `purgeable` fields to `process.getSystemMemoryInfo()` for macOS by cucbin · Pull Request #47628 · electron/electron

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

  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.

…mMemoryInfo().

…yInfo().

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

cucbin · 2025-08-19T07:03:02Z

Hi @codebytere
I have rebased the code with latest code. Could you please help to speed up the PR's progress?
Thanks.

release-clerk · 2025-08-20T07:49:44Z

Release Notes Persisted

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

trop · 2025-08-20T07:49:50Z

I was unable to backport this PR to "38-x-y" cleanly;
you will need to perform this backport manually.

trop · 2025-08-20T07:49:53Z

I was unable to backport this PR to "37-x-y" cleanly;
you will need to perform this backport manually.

trop · 2025-08-21T07:58:27Z

@cucbin has manually backported this PR to "37-x-y", please check out #48143

trop · 2025-08-21T09:25:31Z

@cucbin has manually backported this PR to "38-x-y", please check out #48146

…moryInfo()` for macOS (electron#47628) * fix: Optimize the value of memory.free in the return data of getSystemMemoryInfo(). * fix: Improve the value of memory in the return data of getSystemMemoryInfo(). * fix: complete API doc. * Update docs/api/process.md Co-authored-by: Will Anderson <will@itsananderson.com> * fix: update name to fileBacked. * fix: fix with code conflict --------- Co-authored-by: Will Anderson <will@itsananderson.com>

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 MarshallOfSound, itsananderson, nikwen and samuelmaddock 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

cucbin and others added 6 commits August 19, 2025 14:30

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

6b9c106

…mMemoryInfo().

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

3758d7a

…yInfo().

fix: complete API doc.

d00d11d

Update docs/api/process.md

9671d81

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

fix: update name to fileBacked.

a3d095c

fix: fix with code conflict

e0327c1

cucbin force-pushed the fix/correct_mem_free_value_in_get_system_mem_info branch from b68f43c to e0327c1 Compare August 19, 2025 06:32

codebytere merged commit 83a5ba1 into electron:main Aug 20, 2025
52 of 54 checks passed

trop bot removed the target/38-x-y PR should also be added to the "38-x-y" branch. label Aug 20, 2025

trop bot added needs-manual-bp/38-x-y needs-manual-bp/37-x-y and removed target/37-x-y PR should also be added to the "37-x-y" branch. labels Aug 20, 2025

cucbin mentioned this pull request Aug 21, 2025

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

Merged

trop bot added in-flight/37-x-y and removed needs-manual-bp/37-x-y labels Aug 21, 2025

cucbin mentioned this pull request Aug 21, 2025

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

Merged

trop bot added in-flight/38-x-y and removed needs-manual-bp/38-x-y labels Aug 21, 2025

trop bot added merged/37-x-y PR was merged to the "37-x-y" branch. merged/38-x-y PR was merged to the "38-x-y" branch. and removed in-flight/37-x-y in-flight/38-x-y labels Aug 28, 2025

sunfish-shogi mentioned this pull request Sep 1, 2025

macOS のメモリ使用率に fileBacked を反映 sunfish-shogi/shogihome#1321

Closed

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 Aug 19, 2025

Uh oh!

Uh oh!

release-clerk bot commented Aug 20, 2025

Uh oh!

trop bot commented Aug 20, 2025

Uh oh!

trop bot commented Aug 20, 2025

Uh oh!

trop bot commented Aug 21, 2025

Uh oh!

trop bot commented Aug 21, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

cucbin commented Jul 1, 2025 •

edited by nikwen

Loading

nikwen left a comment •

edited

Loading

nikwen commented Jul 18, 2025 •

edited

Loading