Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: add warning for accessing builders after consumption #443

Merged
merged 2 commits into from
Oct 1, 2024
Merged

docs: add warning for accessing builders after consumption #443

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7046ca0
docs: add warning for accessing builder after consumption
cwaldren-ld Sep 30, 2024
e9489b8
add more docs for client-side SDK
cwaldren-ld Sep 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 50 additions & 9 deletions libs/client-sdk/include/launchdarkly/client_side/bindings/c/config/builder.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down Expand Up @@ -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.
*/
Expand Down Expand Up @@ -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.
*/
Expand All @@ -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.
*/
Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand Down
8 changes: 5 additions & 3 deletions libs/common/include/launchdarkly/bindings/c/context_builder.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
50 changes: 42 additions & 8 deletions libs/server-sdk/include/launchdarkly/server_side/bindings/c/config/builder.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*
Expand All @@ -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.
*
Expand All @@ -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.
*
Expand Down Expand Up @@ -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.
*/
Expand Down Expand Up @@ -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.
*/
Expand All @@ -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.
Expand Down
Loading