Document celerity::allow_by_ref, remove CELERITY_STRICT_CGF_SAFETY macro

Author: fknorr

docs/pitfalls.md

@@ -31,10 +31,10 @@ have been unwound by the time it is being called.
 
 For this reason Celerity by default enforces that tasks only capture
 surrounding variables by value, rather than by reference. If you know what
-you are doing and would like to disable this check, you can define the
-following macro before including Celerity:
+you are doing and would like to disable this check, you can use the
+`distr_queue::submit` overload accepting reference captures:
 
 ```cpp
-#define CELERITY_STRICT_CGF_SAFETY 0
-#include <celerity/celerity.h>
+distr_queue q;
+q.submit(celerity::allow_by_ref, [&](celerity::handler &cgh) {...});
 ```

include/buffer.h

@@ -127,7 +127,7 @@ class buffer {
 	//
 	// (The reason why we make this a shared_ptr is so that Celerity buffers
 	// still satisfy StandardLayoutType, which we use as a crude safety check;
-	// see CELERITY_STRICT_CGF_SAFETY macro).
+	// see distr_queue::submit).
 	std::shared_ptr<cl::sycl::buffer<DataT, Dims>> faux_buf;
 };
 

include/distr_queue.h

@@ -6,10 +6,6 @@
 #include "runtime.h"
 #include "task_manager.h"
 
-#if !defined(CELERITY_STRICT_CGF_SAFETY)
-#define CELERITY_STRICT_CGF_SAFETY 1
-#endif
-
 namespace celerity {
 namespace detail {
 
@@ -23,8 +19,9 @@ namespace detail {
 
 } // namespace detail
 
-struct allow_by_ref_t {
-} inline constexpr allow_by_ref{};
+struct allow_by_ref_t {};
+
+inline constexpr allow_by_ref_t allow_by_ref{};
 
 class distr_queue {
   public:
@@ -40,21 +37,32 @@ class distr_queue {
 	distr_queue& operator=(const distr_queue&) = delete;
 	distr_queue& operator=(distr_queue&&) = delete;
 
+	/**
+	 * Submits a command group to the queue.
+	 *
+	 * Invoke via `q.submit(celerity::allow_by_ref, [&](celerity::handler &cgh) {...})`.
+	 *
+	 * With this overload, CGF may capture by-reference. This may lead to lifetime issues with asynchronous execution, so using the `submit(cgf)` overload is
+	 * preferred in the common case.
+	 */
 	template <typename CGF>
 	void submit(allow_by_ref_t, CGF cgf) {
 		// (Note while this function could be made static, it must not be! Otherwise we can't be sure the runtime has been initialized.)
-		detail::runtime::get_instance().get_task_manager().create_task(cgf);
+		detail::runtime::get_instance().get_task_manager().create_task(std::move(cgf));
 	}
 
+	/**
+	 * Submits a command group to the queue.
+	 *
+	 * CGF must not capture by reference. This is a conservative safety check to avoid lifetime issues when command groups are executed asynchronously.
+	 *
+	 * If you know what you are doing, you can use the `allow_by_ref` overload of `submit` to bypass this check.
+	 */
 	template <typename CGF>
 	void submit(CGF cgf) {
-#if CELERITY_STRICT_CGF_SAFETY
 		static_assert(detail::is_safe_cgf<CGF>, "The provided command group function is not multi-pass execution safe. Please make sure to only capture by "
 		                                        "value. If you know what you're doing, use submit(celerity::allow_by_ref, ...).");
-#endif
-
-		// (Note while this function could be made static, it must not be! Otherwise we can't be sure the runtime has been initialized.)
-		detail::runtime::get_instance().get_task_manager().create_task(cgf);
+		submit(allow_by_ref, std::move(cgf));
 	}
 
 	/**