pass context to wait set, and provide fini function for context (#163)

* pass context to wait set

Signed-off-by: William Woodall <william@osrfoundation.org>

* add fini for context

Signed-off-by: William Woodall <william@osrfoundation.org>

rmw/include/rmw/init.h

@@ -108,6 +108,33 @@ RMW_WARN_UNUSED
 rmw_ret_t
 rmw_shutdown(rmw_context_t * context);
 
+/// Finalize a context.
+/**
+ * The context to be finalized must have been previously initialized with
+ * `rmw_init()`, and then later invalidated with `rmw_shutdown()`.
+ * If context is `NULL`, then `RMW_RET_INVALID_ARGUMENT` is returned.
+ * If context is zero-initialized, then `RMW_RET_INVALID_ARGUMENT` is returned.
+ * If context is initialized and valid (`rmw_shutdown()` was not called on it),
+ * then `RMW_RET_INVALID_ARGUMENT` is returned.
+ *
+ * <hr>
+ * Attribute          | Adherence
+ * ------------------ | -------------
+ * Allocates Memory   | Yes
+ * Thread-Safe        | No
+ * Uses Atomics       | Yes
+ * Lock-Free          | Yes [1]
+ * <i>[1] if `atomic_is_lock_free()` returns true for `atomic_uint_least64_t`</i>
+ *
+ * \return `RMW_RET_OK` if the shutdown was completed successfully, or
+ * \return `RMW_RET_INVALID_ARGUMENT` if any arguments are invalid, or
+ * \return `RMW_RET_ERROR` if an unspecified error occur.
+ */
+RMW_PUBLIC
+RMW_WARN_UNUSED
+rmw_ret_t
+rmw_context_fini(rmw_context_t * context);
+
 #ifdef __cplusplus
 }
 #endif

rmw/include/rmw/rmw.h

@@ -521,18 +521,26 @@ rmw_trigger_guard_condition(const rmw_guard_condition_t * guard_condition);
 
 /// Create a wait set to store conditions that the middleware will block on.
 /**
+ * This function can fail, and therefore return `NULL`, if:
+ *   - context is `NULL`
+ *   - context is invalid
+ *   - memory allocation fails during wait set creation
+ *   - an unspecified error occurs
+ *
  * If `max_conditions` is `0`, the wait set can store an unbounded number of
  * conditions to wait on.
  * If `max_conditions` is greater than `0`, the number of conditions that can
  * be attached to the wait set is bounded at `max_conditions`.
+ *
+ * \param[in] context init context that this node should be associated with
  * \param[in] max_conditions
  *   The maximum number of conditions that can be attached to the wait set.
  * \return A pointer to the created wait set, `NULL` if an error occurred.
  */
 RMW_PUBLIC
 RMW_WARN_UNUSED
 rmw_wait_set_t *
-rmw_create_wait_set(size_t max_conditions);
+rmw_create_wait_set(rmw_context_t * context, size_t max_conditions);
 
 RMW_PUBLIC
 RMW_WARN_UNUSED