From 3a176aea23e491f3e24ff3a98b244a68059590c8 Mon Sep 17 00:00:00 2001
From: William Woodall <william+github@osrfoundation.org>
Date: Thu, 24 Jan 2019 19:43:46 -0800
Subject: [PATCH] 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>
Signed-off-by: Devin Bonnie <dbbonnie@amazon.com>
---
 rmw/include/rmw/init.h | 27 +++++++++++++++++++++++++++
 rmw/include/rmw/rmw.h  | 10 +++++++++-
 2 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/rmw/include/rmw/init.h b/rmw/include/rmw/init.h
index 5d4426b9..95fa48a2 100644
--- a/rmw/include/rmw/init.h
+++ b/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
diff --git a/rmw/include/rmw/rmw.h b/rmw/include/rmw/rmw.h
index a47767d2..2310b9ff 100644
--- a/rmw/include/rmw/rmw.h
+++ b/rmw/include/rmw/rmw.h
@@ -521,10 +521,18 @@ 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.
@@ -532,7 +540,7 @@ rmw_trigger_guard_condition(const rmw_guard_condition_t * guard_condition);
 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