Mechanize interface generation, part 2 #43

kulp · 2020-07-15T00:54:49Z

Goals

Demonstrate improved predictability of the Rust interface (how closely the Rust interface follows the C interface)
Reduce the risk of failing to implement an entry point from the C library
Increase the likelihood that any API changes or additions in future GNU lightning versions will either be supported automatically, or manifested as build failures in lightning-sys, as opposed to being hidden

Means

Using the foundation laid in #32, the current PR implements a pattern-matching paradigm to generate public entry point wrappers.

Every jit_ macro exposed by GNU lightning will either match a pattern (and have a generated entry point) or fail to match (and cause a build error).
This contrasts with the previous paradigm where an entry points was maintained manually, which contributed to causing some entry points to be missed (Add missing implementations #34, Export some more predicates #35, Add (and correct) some entry points #37, Add more entry points #42).

Gains

The Rust interface hews more closely to the C interface, reducing surprise for the user.
The risk of some kinds of bugs may be reduced, by decreasing the number of failure modes.
Self-checking is improved, since the new mechanism generates simple test cases to demonstrate that that all jit_-macro entry points advertised by GNU lightning's lightning.h exist, and (in most cases) that the entry points can be called with zeroed parameters without crashing.
The net volume of code to maintain (even including what was introduced in Mechanize interface generation, part 1 #32) is decreased somewhat, after accounting for the generated tests that did not previously exist.

Costs

The new implementation (including work done in #32) carries a significant burden of complexity, especially in macros. The use of tt-call makes the macros more composable and understandable individually, but contributes to the verbosity of the macro implementation.

codecov · 2020-07-15T01:54:41Z

Codecov Report

❗ No coverage uploaded for pull request base (master@6271686). Click here to learn what that means.
The diff coverage is n/a.

kulp · 2020-07-15T03:58:40Z

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "lightning-sys"
 version = "0.2.1"
-authors = ["Peter Elliott <pelliott@ualberta.ca>"]
+authors = ["Peter Elliott <pelliott@ualberta.ca>", "Darren Kulp <darren@kulp.ch>"]


I hope adding my name is all right here. I do not care so much, but I thought it would make sense to match the crates.io ownership list.

About time :^)

kulp · 2020-07-29T02:50:24Z

I am planning to get back to this soon (at worst, by early August), with robust justification; I just ended up working on other things for a while.

`jit_entry`-style support for aliases of these functions will not be ready right away. For convenience, collect these aliases for specific entry points that are not provided by `jit_entry` yet.

This stops jit_register_p from being split into `jit_registe`, `r`, `_p`.

Check for entry point existence Introduce infrastructure for top-level wrappers Add explicit ignores for many instructions Convert compilation check to run check

Prevent testing for jit_destroy_state Avoid testing disassembly when not present

`cargo doc` shows that entry points like `JitState::jit_absr_d` were being exposed publicly outside the crate. This seems to be because, despite being in a non-`pub` `mod` named `raw`, they are associated with a `pub` `type` named `JitState`. Hide them internal to the crate for now.

Drop exclusion for destroy_state -- it is safe to call it now.

kulp · 2020-09-05T16:55:47Z

I am splitting the current PR into several new PRs.

Update build.rs with collected mechanization fixes #50 - collected improvements to the build.rs mechanization to support future work
Collect various cleanup changes #51 - general cleanup
Test entry points using mechanization #54 - a part that uses the jit_entry! macros introduced in Mechanize interface generation, part 1 #32 to test for entry point existence
Generate entry points via mechanization and pattern matching #55 - a part that uses the jit_entry! macros to match and implement entry points

This splitting-up should make it easier to evaluate the costs and benefits of the new implementation. Much of the benefit is gained from parts 1-3.

kulp mentioned this pull request Jul 15, 2020

Add more entry points #42

Merged

kulp force-pushed the generate-macros-redux branch from e3f0b36 to d2b8ce9 Compare July 15, 2020 01:51

kulp commented Jul 15, 2020

View reviewed changes

kulp force-pushed the generate-macros-redux branch from d2b8ce9 to 94e9851 Compare July 16, 2020 01:40

kulp mentioned this pull request Jul 16, 2020

Regularize interface naming #44

Merged

kulp added this to the v0.3 milestone Jul 20, 2020

kulp mentioned this pull request Aug 7, 2020

General purpose registers should be distinguished from floating-point ones #47

Open

kulp force-pushed the generate-macros-redux branch from 94e9851 to 6e0e54c Compare August 22, 2020 20:06

kulp added 20 commits August 28, 2020 16:43

Add Darren Kulp to Cargo.toml authors

9728694

Obviate jit_impl_type

4bec7e5

Hoist some aliases that will live awhile

17f284a

`jit_entry`-style support for aliases of these functions will not be ready right away. For convenience, collect these aliases for specific entry points that are not provided by `jit_entry` yet.

Stop assuming invertibility

e2a116d

This stops jit_register_p from being split into `jit_registe`, `r`, `_p`.

Implement many entry points with the new scheme

b0b4449

Check for entry point existence Introduce infrastructure for top-level wrappers Add explicit ignores for many instructions Convert compilation check to run check

Remove remaining uses of paste

d6d3fe0

Constrain JitNode references lifetimes

6a90c22

Interpose jit_filtered and use tt-call

175a698

Introduce is_new_node_func predicate

26b7379

Handle new_node functions only

03ed398

Avoid creating empty parts from jit_r

36249ed

Stop filtering only on jit_new_node

f671fac

Test more entry points

ff94b9f

Prevent testing for jit_destroy_state Avoid testing disassembly when not present

Remove needless jit_alias arm

b13164a

Make lifetimes explicit and regular

22001c5

Correct typo for "implementations"

de4b9a5

Colocate some exports with their cousin aliases

e862d9e

Count entry points

6afae58

Check for 19 jit_new_node* functions

d6edc7d

kulp added 5 commits August 28, 2020 16:43

Count callers of jit_new_node

1de6f6e

Remove needless explicit unit returns

57f6e84

Clarify the role of jit_filtered

0628ce7

Document more macros

ee6225c

Add entry points for destroy_state

62b6eb3

Drop exclusion for destroy_state -- it is safe to call it now.

kulp force-pushed the generate-macros-redux branch from 5739b02 to 62b6eb3 Compare August 28, 2020 23:44

kulp closed this Sep 5, 2020

This was referenced Sep 5, 2020

Collect various cleanup changes #51

Merged

Update build.rs with collected mechanization fixes #50

Merged

kulp mentioned this pull request Sep 18, 2020

Generate entry points via mechanization and pattern matching #55

Merged

kulp deleted the generate-macros-redux branch December 27, 2022 15:58

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Mechanize interface generation, part 2 #43

Mechanize interface generation, part 2 #43

kulp commented Jul 15, 2020 •

edited

codecov bot commented Jul 15, 2020 •

edited

kulp Jul 15, 2020

petelliott Jul 15, 2020

kulp commented Jul 29, 2020

kulp commented Sep 5, 2020 •

edited

Mechanize interface generation, part 2 #43

Mechanize interface generation, part 2 #43

Conversation

kulp commented Jul 15, 2020 • edited

Goals

Means

Gains

Costs

codecov bot commented Jul 15, 2020 • edited

Codecov Report

kulp Jul 15, 2020

Choose a reason for hiding this comment

petelliott Jul 15, 2020

Choose a reason for hiding this comment

kulp commented Jul 29, 2020

kulp commented Sep 5, 2020 • edited

kulp commented Jul 15, 2020 •

edited

codecov bot commented Jul 15, 2020 •

edited

kulp commented Sep 5, 2020 •

edited