Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Implement error codes and exceptions for error handling #766

Draft
wants to merge 97 commits into
base: master
Choose a base branch
from

Conversation

SteffenL
Copy link
Collaborator

@SteffenL SteffenL commented Jun 5, 2022

With this PR I wish to propose changing the API and improving error handling throughout the library in a way that is intended to be backward-compatible for current users of the C API.

This work allows both C API and C++ API users to handle errors or at the very least detect that an error has occurred and then respond accordingly to minimize crashes due to invalid state.

Although this work is not finished, it is a good time to begin discussions.

Specific changes

  • Change void return types to an error code type for all of the functions of the C API that could benefit from returning an error code.
    • This is a binary compatible change for the C API. Existing programs can use a new version of the library with no recompilation required.
  • C++ API now throws exceptions. This is the sane way to report errors in C++. Most users will likely recompile the library anyway (it is header-only) so we do not have to worry too much about binary incompatibilities.
    • Should we allow library users to disable C++ exceptions, i.e. optionally not compile them? I think they should be enabled by default because the result will in many cases be the same: crash
  • C API returns error codes by catching C++ exceptions and extracting error codes from them.
  • The library should have the ability to report its own version. For now there is no distinction between the product version and API version. Let me know what you think about that.
  • The library should have a version compatibility check, i.e. check whether the caller's version is supported by the library.
  • Add a new function to the C API named webview_create_with_options that takes a struct as a parameter.
    • Allows us to expand the options that can be passed to the library, such as initial window size, whether to center the window, initial visibility, etc. We cannot keep changing webview_create when we need more options.
    • The minimum_required_version option is checked for compatibility and allows us to change behavior based on the version set by the caller.
    • I added an option to control initial visibility of the window along with a webview_show function to show the window on-demand. This demonstrates how we can change some behavior while providing backward-compatibility. The new behavior is to hide the window initially which requires users to call webview_show when they are ready.
    • Windows: When the window should be made visible initially:
      • Since 0.11.0: Use new behavior and show the window after embedding the underlying webview.
      • Before 0.11.0: Use old behavior and show the window before embedding the underlying webview.
  • Deprecate webview_create and webview::webview(bool debug, void *wnd).
  • I added @since 0.11 to the new C API functions so that we can track in which version a feature was added, but there is nothing in this project that uses this style of commenting. Later I think we should adapt the documentation comments for a documentation generator.

Tasks

  • Initial C/C++ implementation (draft).
  • Implement visibility option:
    • Windows
    • Linux
    • macOS
  • Update tests.
  • Update examples.
  • Update documentation.
  • Gather feedback.
  • Implement changes based on feedback.

Won't Do

  • Go implementation, tests and examples will not be updated in this PR both to reduce the scope of this PR and because I am not comfortable enough with Go. The core library must however not break compatibility.

@SteffenL SteffenL requested review from justjosias and removed request for justjosias June 5, 2022 23:43
@SteffenL SteffenL force-pushed the up/improve-error-handling branch 3 times, most recently from 98b6187 to 569446a Compare July 8, 2022 17:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants