feature: extreme low memory mode BB

[ludamad]

Title
Add mmap-backed Polynomial allocation gated on BB_SLOW_LOW_MEMORY

---

Motivation

On memory-constrained mobile targets (e.g. zkPassport on iOS/Android) the RAM footprint of large proving keys and working polynomials is the main source of crashes. We already proved in a local PoC that mapping polynomials to disk with mmap slashes resident memory while keeping the API intact.

What & How

• Compile-time gate:

  #ifdef BB_SLOW_LOW_MEMORY
  // new mmap-backed storage
  #else
  // current heap allocation path
  #endif

• Behavior:

  • When BB_SLOW_LOW_MEMORY is defined every Polynomial instance is backed by its own anonymous temporary file created with O_TMPFILE (or mkstemp + unlink fallback).
  • Outside that build flag nothing changes ― the class stays purely in-memory.

• Details / Notes

  1. mmap(size, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0)
  2. RAII cleanup: munmap in the destructor; file closes automatically because it’s unlinked right after creation.
  3. Keep constructor, iterators, and operator[] unchanged so existing call-sites compile untouched.

Acceptance criteria

• Allowing for significant slowdown, ability to run in a memory-constrained docker environment (e.g. say 1GB for a proving job that normally takes 2GB). This is a proxy for showing that mobile devices will evict pages as needed to keep our app within memory.

Potential followups

• Use madvise? (dubious if needed, complicated)

[johnathan79717]

As Adam pointed out on Slack DM, the POC approach by claude code produces a lot of duplicated code. I think it will also make it much harder to maintain because changes need to be replicated in both classes. To solve that, I see two approaches:

1. Use one class. Use #ifdef BB_SLOW_LOW_MEMORY whenever we need different behavior. This could result in uglier code though.
2. Extract common code and put in a abstract base class. Derived classes can have different behavior in storage.

I'll do a little more exploration to see which way I want to proceed with.

[ludamad]

The abstract base class approach might not be necessary if we can simply provide an allocator somehow (could be a template param) as I'm hoping the differences are purely constrained to the initialization. Eventually a runtime flag is preferable to ifdef

[johnathan79717]

You're right. For ifdef only, we can probably just

#ifdef BB_SLOW_LOW_MEMORY
template <typename T> using SharedShiftedVirtualZeroesArray = FileBackedShiftedVirtualZeroesArray<T>;
#else
template <typename T> using SharedShiftedVirtualZeroesArray = MemoryBackedSharedShiftedVirtualZeroesArray<T>;
#endif

[ledwards2225]

@johnathan79717 Is it safe to say this issue can be closed?

[johnathan79717]

@johnathan79717 Is it safe to say this issue can be closed?

Yes!