Repository navigation
Add deinit() to displays; deprecate displayio.release_displays() - #11914
Conversation
BusDisplay, EPaperDisplay, FramebufferDisplay and zephyr_display.Display get a deinit() method. It releases the display and, unless another display uses it, the display's bus, freeing their pins. If the display is supervisor.runtime.display, the primary display is cleared and the terminal stops. supervisor.runtime.display.deinit() does what release_displays() is used for: release a built-in display, or one kept from an earlier run. Methods called on a released display subclass instance now raise "Object has been deinitialized" instead of using the released slot. Refs adafruit#8675 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Mark displayio.release_displays() deprecated in its docstring, and point other docstrings, examples and docs/environment.rst to deinit() on the display instead. It still works, with no runtime warning. Refs adafruit#8675 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
"Too many display busses; forgot displayio.release_displays() ?" is now "Too many display buses; deinit() unused displays". Regenerating circuitpython.pot also drops two stale source locations for "%q must be <= %d". Refs adafruit#8675 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The display deinit() changes add about 240 bytes of flash, which made some translated builds of these boards overflow. - itsybitsy_m0_express, qtpy_m0_haxpress, snekboard: turn off codeop, errno and rainbowio, as on Feather M0 Express and Metro M0 Express. pulseio stays off on itsybitsy_m0_express, which doesn't fit with it on. - bluemicro840, bless_dev_board_multi_sensor: turn off codeop and rainbowio. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
Looks good.
Non-blocking question:
should a second deinit() be a no-op? On a direct instance it raises AttributeError, on a subclass it does nothing.
Tested on a Metro RP2350 with FourWire + BusDisplay on D9/D10, no panel attached.
CI builds: main at 101416a vs this PR at 78249b6.
| Case | main | PR |
|---|---|---|
d.deinit() |
AttributeError |
ok |
| D9 free after deinit | in use | free |
User busio.SPI still usable |
ok | ok |
| Bound method called after deinit | ran on released display | deinitialized error |
Second d.deinit(), direct instance |
n/a | AttributeError |
Second deinit(), subclass |
n/a | no-op |
| Subclass method after deinit | returned 64 | deinitialized error |
runtime.display.deinit(), then runtime.display |
still <BusDisplay> |
None, D9 free |
release_displays(), then old object |
AttributeError |
AttributeError |
| Too many buses error | old text | new text |
|
@mikeysklar Thanks for the testing and review! Right now a display in the internal static display table is set to have the In a later stage of addressing #8675, we would probably start allocating displays separately, which would remove some code (and add some), and could have a deinited flag. Right now adding that flag would add a lot of extra code. |
|
That is fair. I don't want to deal with flash shortages due to code bloat on this either. Good to merge. |
|
@tannewt since this is an API change and also deep in displayio, I'll wait for your review too. |
tannewt
left a comment
There was a problem hiding this comment.
This looks good to me! I'm surprised they didn't have deinit() already!
release_displays(). #8675 (@tannewt)Code by Claude, reviewed by @dhalbert.
This is the first stage of #8675. Displays get
deinit(), anddisplayio.release_displays()is deprecated in the docs only. It still works, with no runtime warning.We can add a
FutureWarningonce 11.x has largely replaced 10.x.Moving I2C and SPI objects and removing
release_displays()are left for later.Problem
The only way to release a display was
displayio.release_displays(), which releases every display and display bus at once. None of the display classes haddeinit().Fix
deinit():busdisplay.BusDisplayepaperdisplay.EPaperDisplayframebufferio.FramebufferDisplayzephyr_display.Display(zephyr-cp)deinit()releases the display and its display bus (such asfourwire.FourWireori2cdisplaybus.I2CDisplayBus), so their pins can be used again. The display bus is not released if another display still uses it.deinit()does whatrelease_displays()does, but for just the one display:busio.SPIorbusio.I2Cobject passed to the display bus is not deinitialized, so a bus shared with other devices keeps working. It is deinitialized only when the display bus took it over from an earlier run.supervisor.runtime.displaybecomesNoneand the terminal stops.EPaperDisplay, it waits for a refresh in progress.None-typed, so calling a method on it raisesAttributeError.supervisor.runtime.display.deinit()can and should replacerelease_displays()at the top ofcode.py. Since Release extra displays when code finishes #11702, the primary display is the only one that can outlive a run.deinit()orrelease_displays(), a method called on an instance of a display subclass (such asadafruit_st7789.ST7789) now raises "Object has been deinitialized". Before, it incorrectly used the released display's memory.release_displays()is marked deprecated in its docstring. Other docstrings, theqspibusandusb_videoexamples, anddocs/environment.rstnow refer todeinit().deinit()method in this PR.Testing
deinit()andsupervisor.runtime.display.deinit()were tested on:BusDisplay,FourWireBusDisplayEPaperDisplay, during a refreshFramebufferDisplay,picodviFramebufferDisplay,mipidsi, with a user-created displayzephyr_display.Displayrelease_displays()was checked to still work as before.