Align abstract interfaces, teardown attributes, and moved-from docs#57
Merged
Conversation
cleishm
force-pushed
the
lcd/nvi-and-api-consistency
branch
3 times, most recently
from
771fd31 to
f95bb26
Compare
Convert the lcd::panel and lcd::touch abstract bases to the non-virtual interface pattern: public non-virtual try_*/throwing method pairs with protected do_* hooks that concrete drivers (ili9341, stmpe610) override privately, and protected move operations. This matches the shape of lora::radio and std::pmr::memory_resource. Flatten the lcd config structs: panel::config gains a top-level reset_active_level field (replacing the single-field nested flags struct), and touch::config gains reset_level, interrupt_level, swap_xy, mirror_x, and mirror_y fields (replacing the nested levels and flags structs). idfxx_lcd, idfxx_lcd_touch, idfxx_lcd_ili9341, and idfxx_lcd_touch_stmpe610 move to 2.0.0 for these breaking changes. Remove [[nodiscard]] from teardown operations where callers reasonably ignore the result, per the documented convention: event_loop::try_listener_remove, http::client::try_close, http::server::try_unregister_handler, ota::update::try_abort, and try_unregister_shutdown_handler. Document moved-from object use as undefined behavior across all move-only types (console, event_group, i2c, lcd panel_io, nvs, onewire, ota, queue, spi, task, timer), replacing the previous per-class guarantees that methods return errc::invalid_state. Implementations still attempt to fail safely, but the safe failure is no longer API surface. The net socket types keep their explicit narrow allowance (destroy, move-assign, and is_open()/native_handle() queries); datagram_socket drops its moved-from @RetVal promises. Components with non-breaking changes receive patch version bumps.
cleishm
force-pushed
the
lcd/nvi-and-api-consistency
branch
from
f95bb26 to
407077f
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
API-consistency pass across the released components, following the conventions established in the LoRa work (#56):
Non-virtual interface for abstract bases (breaking — 2.0.0):
lcd::panelandlcd::touchnow expose public non-virtualtry_*/throwing method pairs with protecteddo_*hooks that concrete drivers override privately (matchinglora::radioandstd::pmr::memory_resource), with protected move operations.ili9341andstmpe610updated to privatedo_*overrides; their public surfaces now show only what is driver-specific.Flattened lcd config structs (breaking — same 2.0.0):
panel::config: nested single-fieldflagsstruct replaced by a top-levelreset_active_level.touch::config: nestedlevels/flagsstructs replaced by flatreset_level,interrupt_level,swap_xy,mirror_x,mirror_yfields..flags = {...}spellings at call sites.idfxx_lcd,idfxx_lcd_touch,idfxx_lcd_ili9341,idfxx_lcd_touch_stmpe610→ 2.0.0, with^2.0.0dependency ranges in dependent components and example projects. (panel_io::config::flagsis left as-is — it holds eight genuine bitfields.)[[nodiscard]]teardown sweep (non-breaking):Removed from five deregister/teardown operations where callers reasonably ignore the result, per the documented convention:
event_loop::try_listener_remove,http::client::try_close,http::server::try_unregister_handler,ota::update::try_abort,try_unregister_shutdown_handler. Kept ontry_close_sessionandtry_disable_pmf_config, which are operational rather than teardown.Moved-from contract documented as UB (non-breaking doc change):
All move-only types now document that using a moved-from object (other than destruction or assignment) is undefined behavior, replacing per-class guarantees of
errc::invalid_statereturns. Implementations still attempt to fail safely; that behaviour is just no longer API surface. Applied to console, event_group, i2c, lcd panel_io, nvs, onewire, ota, queue, spi, task, and timer;datagram_socketdrops its moved-from@retvalpromises. The net socket types keep their deliberate narrow allowance (destroy, move-assign,is_open()/native_handle()queries).Versions: components with non-breaking changes are bumped one patch above their last published registry version. Components whose in-repo version is already ahead of the registry (
idfxx_core1.1.0,idfxx_event_group1.0.1,idfxx_task1.0.1, and the never-publishedidfxx_net) keep their pending version — the unreleased increment already covers these changes.