Make destroy_node thread safe

[sloretz]

Blocks #319

I was going to make this part of #319, but I think it would be easier to review separately. This makes Node.handle use the Handle class from #308. It also adds handle.requires(another_handle) to make sure handle is destroyed before another_handle.

Problem this solves

#308 makes destroy_subscription thread safe by delaying destruction if the handle is currently being used. This makes it possible for a subscription to be destroyed after the node; which crashes when doing the same strategy with services using fast-rtps. See #319 (comment) for a better explanation.

Breaking changes

• Previously node.destroy_node() either returned True or raised an exception. I removed the return value since it was only ever True.
• Previously node.handle was set to None after the node was destroyed. Now it raises InvalidHandle when someone tries to use it after it is destroyed.
• previously node.handle was a pycapsule and could be used directly. Now one must use:

  with node.handle as node_capsule:
     ...

How handle.requires() works

Subscriptions must be destroyed before the node that created them, so

subscription.handle.requires(node.handle)

When node.handle.destroy() is called the subscription handle is destroyed first. Once the node handle is no longer being used it will mark itself invalid so no one else can use it. Then the node handle tells the subscription handle to destroy itself. Once the subscription handle is no longer in use it will delete itself, and then tell the node it can destroy itself.

If the user does not call destroy() on either handle, the subscription handle holds a reference to the node handle so the subscription handle will be garbage collected first. The node handle only holds a weak reference to the subscription handle.

Next steps

After incorporating feedback, assuming this approach is OK I would like to merge this PR. Then I'll rebase #319 to make all the other entities require the node so everything can be destroyed safely.

[sloretz]

CI (testing all packages above rclpy)

• Linux (test_params_yaml test_cli.test_params_yaml flaky build_farmer#166)
• Linux-aarch64 (test_params_yaml test_cli.test_params_yaml flaky build_farmer#166)
• macOS
• Windows (test_params_yaml test_cli.test_params_yaml flaky build_farmer#166)

[sloretz]

CI (testing just rclpy)

• Linux
• Linux-aarch64
• macOS
• Windows

[sloretz]

Destruction can be delayed waiting for dependents. Previously self.__valid = False meant the capsule itself has been destroyed. Now setting it to false means destroy() was called and __use_count hit zero. The purpose is to prevent new users of this handle while waiting for dependent handles to be destroyed.

[sloretz]

CI (testing rclpy)

• Linux
• Linux-aarch64
• macOS
• Windows

[dirk-thomas]

LGTM (after convincing myself I understood how the call hierarchy happens)

[sloretz]

CI (testing rclpy with 8c95ea6)

• Linux
• Linux-aarch64
• macOS
• Windows