Update init/shutdown API documentation.#243
Conversation
Constrain behavior for known context states. Signed-off-by: Michel Hidalgo <michel@ekumenlabs.com>
| * guard conditions, and is also required to properly call `rmw_shutdown()`. | ||
| * | ||
| * \pre The given context must be zero initialized. | ||
| * |
There was a problem hiding this comment.
is it possible to ensure that the context will remain zero initialized if rmw_init failed?
There was a problem hiding this comment.
I'll assume you mean rmw_init(). If we can provide an adequate return code, we can rollback what we've done and reset the content of the struct. Note this talks about the rmw_context_t struct and not about any other global state that an rmw implementation may initialize as a side effect. We can't make promises there.
There was a problem hiding this comment.
If it doesn't add much burden to the implementation, I would try to always enforce a "strong failure guarantee" (equivalent to the C++ strong exception safety guarantee), more than only a "basic failure" guarantee).
I'll assume you mean rmw_init()
Yes, edited.
Note this talks about the rmw_context_t struct and not about any other global state that an rmw implementation may initialize as a side effect
yes, there might be visible side effects that we can't control.
There was a problem hiding this comment.
If it doesn't add much burden to the implementation, I would try to always enforce a "strong failure guarantee"
Yeah, I know where you're going. Because I don't know for sure what is (or will be) out there, I try not to commit to more than it is strictly necessary for it not to be imprecise. In this specific case, I'd rather not make strong guarantees about anything but the struct just yet. @wjwwood for feedback.
There was a problem hiding this comment.
I don't mind one way or the other. We don't usually reset structures on failure, but we do things like reclaim resources that would otherwise be leaked, which is a little more important in my opinion. The user could always re-zero init the structure if it failed. I think the only important guarantee is that no resources are leaked, so it is not needed to call shutdown or fini on it and it's say to overwrite it.
Signed-off-by: Michel Hidalgo <michel@ekumenlabs.com>
|
Alright, going in! |
Signed-off-by: Michel Hidalgo <michel@ekumenlabs.com>
Signed-off-by: Michel Hidalgo <michel@ekumenlabs.com>
Constrain behavior for known context states. Alternative to #242.