docs: add warning for accessing builders after consumption (#443)

We've had multiple issues filed for accessing builders that have already been consumed. Our docs need to be more prescriptive on this issue.
launchdarkly · Oct 1, 2024 · 23625ca · 23625ca
1 parent e8ca616
commit 23625ca
Show file tree

Hide file tree

Showing 3 changed files with 97 additions and 20 deletions.
diff --git a/libs/client-sdk/include/launchdarkly/client_side/bindings/c/config/builder.h b/libs/client-sdk/include/launchdarkly/client_side/bindings/c/config/builder.h
@@ -264,31 +264,41 @@ LD_EXPORT(void)
 LDClientConfigBuilder_DataSource_UseReport(LDClientConfigBuilder b,
                                            bool use_report);
 /**
- * Set the streaming configuration for the builder.
+ * Set the streaming configuration for the builder. The builder is automatically
+ * freed.
+ *
+ * WARNING: Do not call any other
+ * LDDataSourceStreamBuilder function on the provided LDDataSourceStreamBuilder
+ * after calling this function. It is undefined behavior.
  *
  * A data source may either be streaming or polling. Setting a streaming
  * builder indicates the data source will use streaming. Setting a polling
  * builder will indicate the use of polling.
  *
  * @param b Client config builder. Must not be NULL.
  * @param stream_builder The streaming builder. The builder is consumed; do not
- * free it.
+ * free it. Must not be NULL.
  */
 LD_EXPORT(void)
 LDClientConfigBuilder_DataSource_MethodStream(
     LDClientConfigBuilder b,
     LDDataSourceStreamBuilder stream_builder);
 
 /**
- * Set the polling configuration for the builder.
+ * Set the polling configuration for the builder. The builder is automatically
+ * freed
+ *
+ * WARNING: Do not call any other
+ * LDDataSourcePollBuilder function on the provided  LDDataSourcePollBuilder
+ * after calling this function. It is undefined behavior.
  *
  * A data source may either be streaming or polling. Setting a stream
  * builder indicates the data source will use streaming. Setting a polling
  * builder will indicate the use of polling.
  *
  * @param b Client config builder. Must not be NULL.
  * @param poll_builder The polling builder. The builder is consumed; do not free
- * it.
+ * it. Must not be NULL.
  */
 LD_EXPORT(void)
 LDClientConfigBuilder_DataSource_MethodPoll(
@@ -396,7 +406,13 @@ LDClientConfigBuilder_HttpProperties_Header(LDClientConfigBuilder b,
                                             char const* value);
 
 /**
- * Sets the TLS options builder. The builder is consumed; do not free it.
+ * Sets the TLS options builder. The builder is automatically freed.
+ *
+ * WARNING: Do not call any other
+ * LDClientHttpPropertiesTlsBuilder function on the provided
+ * LDClientHttpPropertiesTlsBuilder after calling this function.
+ * It is undefined behavior.
+ *
  * @param b Client config builder. Must not be NULL.
  * @param tls_builder The TLS options builder. Must not be NULL.
  */
@@ -468,7 +484,14 @@ LD_EXPORT(void)
 LDClientConfigBuilder_Logging_Disable(LDClientConfigBuilder b);
 
 /**
- * Configures the SDK with basic logging.
+ * Configures the SDK with basic logging. The logging builder is
+ * automatically freed.
+ *
+ * WARNING: Do not call any other
+ * LDLoggingBasicBuilder function on the provided
+ * LDLoggingBasicBuilder after calling this function.
+ * It is undefined behavior.
+ *
  * @param b  Client config builder. Must not be NULL.
  * @param basic_builder The basic logging builder. Must not be NULL.
  */
@@ -477,7 +500,13 @@ LDClientConfigBuilder_Logging_Basic(LDClientConfigBuilder b,
                                     LDLoggingBasicBuilder basic_builder);
 
 /**
- * Configures the SDK with custom logging.
+ * Configures the SDK with custom logging. The custom builder is automatically
+ * freed.
+ *
+ * WARNING: Do not call any other
+ * LDLoggingCustomBuilder function on the provided LDLoggingCustomBuilder after
+ * calling this function. It is undefined behavior.
+ *
  * @param b  Client config builder. Must not be NULL.
  * @param custom_builder The custom logging builder. Must not be NULL.
  */
@@ -514,7 +543,14 @@ LDPersistenceCustomBuilder_Implementation(LDPersistenceCustomBuilder b,
                                           struct LDPersistence impl);
 
 /**
- * Configures the SDK with custom persistence.
+ * Configures the SDK with custom persistence. The persistence builder
+ * is automatically freed.
+ *
+ * WARNING: Do not call any other
+ * LDPersistenceCustomBuilder function on the provided
+ * LDPersistenceCustomBuilder after calling this function. It is undefined
+ * behavior.
+ *
  * @param b  Client config builder. Must not be NULL.
  * @param custom_builder The custom persistence builder. Must not be NULL.
  * @return
@@ -532,7 +568,12 @@ LD_EXPORT(void)
 LDClientConfigBuilder_Persistence_None(LDClientConfigBuilder b);
 
 /**
- * Creates an LDClientConfig. The LDClientConfigBuilder is consumed.
+ * Creates an LDClientConfig. The builder is automatically freed.
+ *
+ * WARNING: Do not call any other
+ * LDClientConfigBuilder function on the provided LDClientConfigBuilder after
+ * calling this function. It is undefined behavior.
+ *
  * On success, the config will be stored in out_config; otherwise,
  * out_config will be set to NULL and the returned LDStatus will indicate
  * the error.

diff --git a/libs/common/include/launchdarkly/bindings/c/context_builder.h b/libs/common/include/launchdarkly/bindings/c/context_builder.h
@@ -35,10 +35,12 @@ LD_EXPORT(void)
 LDContextBuilder_Free(LDContextBuilder builder);
 
 /**
- * Construct a context from a context builder.
+ * Construct a context from a context builder. The builder is automatically
+ * freed.
  *
- * When building a context using @ref LDContextBuilder_Build the builder will be
- * consumed and you do not need to call @ref LDContextBuilder_Free.
+ * WARNING: Do not call any other
+ * LDContextBuilder function on the provided LDContextBuilder after
+ * calling this function. It is undefined behavior.
  *
  * @param builder The builder to build a context from. Must not be NULL.
  * @return The built context.

diff --git a/libs/server-sdk/include/launchdarkly/server_side/bindings/c/config/builder.h b/libs/server-sdk/include/launchdarkly/server_side/bindings/c/config/builder.h
@@ -185,7 +185,13 @@ LDServerConfigBuilder_Events_PrivateAttribute(LDServerConfigBuilder b,
                                               char const* attribute_reference);
 
 /**
- * Configures the Background Sync data system with a Streaming synchronizer.
+ * Configures the Background Sync data system with a Streaming synchronizer. The
+ * builder is automatically freed.
+ *
+ * WARNING: Do not call any other
+ * LDServerDataSourceStreamBuilder function on the provided
+ * LDServerDataSourceStreamBuilder after calling this function. It is undefined
+ * behavior.
  *
  * This is the default data system configuration for the SDK.
  *
@@ -196,15 +202,21 @@ LDServerConfigBuilder_Events_PrivateAttribute(LDServerConfigBuilder b,
  *
  * @param b Server config builder. Must not be NULL.
  * @param stream_builder The streaming builder. The builder is consumed; do not
- * free it.
+ * free it. Must not be NULL.
  */
 LD_EXPORT(void)
 LDServerConfigBuilder_DataSystem_BackgroundSync_Streaming(
     LDServerConfigBuilder b,
     LDServerDataSourceStreamBuilder stream_builder);
 
 /**
- * Configures the Background Sync data system with a Polling synchronizer.
+ * Configures the Background Sync data system with a Polling synchronizer. The
+ * builder is automatically freed.
+ *
+ * WARNING: Do not call any other
+ * LDServerDataSourcePollBuilder function on the provided
+ * LDServerDataSourcePollBuilder after calling this function. It is undefined
+ * behavior.
  *
  * This synchronizer may be chosen to override the default Streaming mode.
  *
@@ -214,17 +226,23 @@ LDServerConfigBuilder_DataSystem_BackgroundSync_Streaming(
  *
  * @param b Server config builder. Must not be NULL.
  * @param poll_builder The polling builder. The builder is consumed; do not free
- * it.
+ * it. Must not be NULL.
  */
 LD_EXPORT(void)
 LDServerConfigBuilder_DataSystem_BackgroundSync_Polling(
     LDServerConfigBuilder b,
     LDServerDataSourcePollBuilder poll_builder);
 
 /**
- * Configures the Lazy Load data system. This method is mutually exclusive with
+ * Configures the Lazy Load data system. The builder is automatically consumed.
+ *
+ * This method is mutually exclusive with
  * the BackgroundSync_Polling and BackgroundSync_Streaming builders.
  *
+ * WARNING: Do not call any other
+ * LDServerLazyLoadBuilder function on the provided LDServerLazyLoadBuilder
+ * after calling this function. It is undefined behavior.
+ *
  * In this mode the SDK will query a data source on-demand as required, with an
  * in-memory cache to reduce the number of queries.
  *
@@ -396,7 +414,13 @@ LDServerConfigBuilder_HttpProperties_Header(LDServerConfigBuilder b,
                                             char const* value);
 
 /**
- * Sets the TLS options builder. The builder is consumed; do not free it.
+ * Sets the TLS options builder. The builder is automatically freed.
+ *
+ * WARNING: Do not call any other
+ * LDServerHttpPropertiesTlsBuilder function on the provided
+ * LDServerHttpPropertiesTlsBuilder after calling this function. It is undefined
+ * behavior.
+ *
  * @param b Server config builder. Must not be NULL.
  * @param tls_builder The TLS options builder. Must not be NULL.
  */
@@ -468,7 +492,12 @@ LD_EXPORT(void)
 LDServerConfigBuilder_Logging_Disable(LDServerConfigBuilder b);
 
 /**
- * Configures the SDK with basic logging.
+ * Configures the SDK with basic logging. The builder is automatically freed.
+ *
+ * WARNING: Do not call any other
+ * LDLoggingBasicBuilder function on the provided LDLoggingBasicBuilder after
+ * calling this function. It is undefined behavior.
+ *
  * @param b  Server config builder. Must not be NULL.
  * @param basic_builder The basic logging builder. Must not be NULL.
  */
@@ -486,7 +515,12 @@ LDServerConfigBuilder_Logging_Custom(LDServerConfigBuilder b,
                                      LDLoggingCustomBuilder custom_builder);
 
 /**
- * Creates an LDClientConfig. The LDServerConfigBuilder is consumed.
+ * Creates an LDClientConfig. The builder is automatically freed.
+ *
+ * WARNING: Do not call any other
+ * LDServerConfigBuilder function on the provided LDServerConfigBuilder after
+ * calling this function. It is undefined behavior.
+ *
  * On success, the config will be stored in out_config; otherwise,
  * out_config will be set to NULL and the returned LDStatus will indicate
  * the error.