Rename FFI types, functions and enums in preparation for 1.0 #73
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
# What does this PR do? This PR updates the names used in the libdatadog API as discussed in the 1.0 discussion meeting. In particular, the following concerns were addressed: * Namespace names -- `ddog_` for common-ffi, `ddog_prof_` for profiling-ffi. This avoids having something like `ddog_Line` which is very specific to profiling be at the top of the namespace. * Fixed inconsistency in destructors: we had `free`, `delete` and `drop`. We now use `drop` everywhere. * Updated namespacing for nested things. E.g. the result of `ddog_prof_Exporter_new` is a `ddog_prof_Exporter_NewResult* . * Used case to separate structs (CamelCase) from methods (snake_case) One departure from what was discussed in the meeting is how containers/generics are named. I had proposed `ddog_VecTag` and `ddog_SliceU8` but cbindgen really doesn't like it. Rather than fight cbindigen about it, I settled for `ddog_Vec_tag` and `ddog_Slice_U8`. Hopefully that is acceptable. # Motivation As our API grows, having a more consistent naming will hopefully help people navigate it. We still have a bit of a weird mix of what goes on `common.h` vs `profiling.h`, but I'll leave changing that for a later PR. Furthermore, it looked to me like 0.9-to-1.0 was a good time to address these concerns. # Additional Notes To the best of my knowledge, here's the complete list of all types changed: | **Kind** | **0.9** | **1.0** | |:--------:|--------------------------------------|----------------------------------------------| | Type | ddog_Endpoint_ddog_Agentless_Body | ddog_Endpoint_ddog_prof_Agentless_Body | | Type | ddog_Slice_c_char | ddog_Slice_CChar | | Type | ddog_Slice_i64 | ddog_Slice_I64 | | Type | ddog_Slice_u8 | ddog_Slice_U8 | | Type | ddog_Vec_tag | ddog_Vec_Tag | | Function | ddog_Vec_tag_drop | ddog_Vec_Tag_drop | | Function | ddog_Vec_tag_new | ddog_Vec_Tag_new | | Function | ddog_Vec_tag_parse | ddog_Vec_Tag_parse | | Function | ddog_Vec_tag_push | ddog_Vec_Tag_push | | Enum | DDOG_PUSH_TAG_RESULT_ERR | DDOG_VEC_TAG_PUSH_RESULT_ERR | | Enum | DDOG_PUSH_TAG_RESULT_OK | DDOG_VEC_TAG_PUSH_RESULT_OK | | Type | ddog_PushTagResult | ddog_Vec_Tag_PushResult | | Function | ddog_PushTagResult_drop | ddog_Vec_Tag_PushResult_drop | | Type | ddog_PushTagResult_Tag | ddog_Vec_Tag_PushResult_Tag | | Type | ddog_Vec_u8 | ddog_Vec_U8 | | Function | ddog_Vec_u8_as_slice | ddog_Vec_U8_as_slice | | Type | ddog_ParseTagsResult | ddog_VecTag_ParseResult | | Type | ddog_EncodedProfile | ddog_prof_EncodedProfile | | Type | ddog_ProfileExporter | ddog_prof_Exporter | | Function | ddog_ProfileExporter_delete | ddog_prof_Exporter_drop | | Type | ddog_File | ddog_prof_Exporter_File | | Function | ddog_ProfileExporter_new | ddog_prof_Exporter_new | | Enum | DDOG_NEW_PROFILE_EXPORTER_RESULT_ERR | DDOG_PROF_EXPORTER_NEW_RESULT_ERR | | Enum | DDOG_NEW_PROFILE_EXPORTER_RESULT_OK | DDOG_PROF_EXPORTER_NEW_RESULT_OK | | Type | ddog_NewProfileExporterResult | ddog_prof_Exporter_NewResult | | Function | ddog_NewProfileExporterResult_drop | ddog_prof_Exporter_NewResult_drop | | Type | ddog_NewProfileExporterResult_Tag | ddog_prof_Exporter_NewResult_Tag | | Type | ddog_Request | ddog_prof_Exporter_Request | | Function | ddog_ProfileExporter_build | ddog_prof_Exporter_Request_build | | Function | ddog_Request_drop | ddog_prof_Exporter_Request_drop | | Function | ddog_ProfileExporter_send | ddog_prof_Exporter_send | | Enum | DDOG_SEND_RESULT_ERR | DDOG_PROF_EXPORTER_SEND_RESULT_ERR | | Enum | DDOG_SEND_RESULT_HTTP_RESPONSE | DDOG_PROF_EXPORTER_SEND_RESULT_HTTP_RESPONSE | | Type | ddog_SendResult | ddog_prof_Exporter_SendResult | | Function | ddog_SendResult_drop | ddog_prof_Exporter_SendResult_drop | | Type | ddog_SendResult_Tag | ddog_prof_Exporter_SendResult_Tag | | Type | ddog_Slice_file | ddog_prof_Exporter_Slice_File | | Type | ddog_Function | ddog_prof_Function | | Type | ddog_Label | ddog_prof_Label | | Type | ddog_Line | ddog_prof_Line | | Type | ddog_Location | ddog_prof_Location | | Type | ddog_Mapping | ddog_prof_Mapping | | Type | ddog_Period | ddog_prof_Period | | Type | ddog_Profile | ddog_prof_Profile | | Function | ddog_Profile_add | ddog_prof_Profile_add | | Function | ddog_Profile_free | ddog_prof_Profile_drop | | Function | ddog_Profile_new | ddog_prof_Profile_new | | Function | ddog_Profile_reset | ddog_prof_Profile_reset | | Function | ddog_Profile_serialize | ddog_prof_Profile_serialize | | Enum | DDOG_SERIALIZE_RESULT_ERR | DDOG_PROF_PROFILE_SERIALIZE_RESULT_ERR | | Enum | DDOG_SERIALIZE_RESULT_OK | DDOG_PROF_PROFILE_SERIALIZE_RESULT_OK | | Type | ddog_SerializeResult | ddog_prof_Profile_SerializeResult | | Function | ddog_SerializeResult_drop | ddog_prof_Profile_SerializeResult_drop | | Type | ddog_SerializeResult_Tag | ddog_prof_Profile_SerializeResult_Tag | | Function | ddog_Profile_set_endpoint | ddog_prof_Profile_set_endpoint | | Type | ddog_Sample | ddog_prof_Sample | | Type | ddog_Slice_label | ddog_prof_Slice_Label | | Type | ddog_Slice_line | ddog_prof_Slice_Line | | Type | ddog_Slice_location | ddog_prof_Slice_Location | | Type | ddog_Slice_value_type | ddog_prof_Slice_ValueType | | Type | ddog_ValueType | ddog_prof_ValueType | # How to test the change? The ffi example apps have been updated and should still compile/work fine. Profilers using libdatadog will need to be updated to use the new names, but otherwise should remain working as before.
ivoanjo
changed the title
gleocadie
approved these changes
Nov 18, 2022
r1viollet
approved these changes
Nov 18, 2022
|
Thanks y'all. I'm going to press the big green merge button BUT I'm happy to follow up on this PR with anything that I've missed here or that we decide we don't quite like. |
ivoanjo
added a commit
to DataDog/dd-trace-rb
that referenced
this pull request
Jan 6, 2023
**What does this PR do?**: Upgrade dd-trace-rb to use the latest libdatadog release (1.0.1.1.0). This libdatadog release includes: * A number of API renames (documented in <DataDog/libdatadog#73>) * The addition of `endpoint_counts`, which we don't use yet, but that needed a few additional changes to API calls and specs. **Motivation**: Keep up with latest improvements and features being added to libdatadog. **Additional Notes**: I've skipped packaging the libdatadog 1.0.0 release, and we're going straight to 1.0.1. **How to test the change?**: The changes in this PR are already covered by the existing tests.
ivoanjo
added a commit
that referenced
this pull request
Jan 6, 2023
**What does this PR do?**: In #73, we changed a number of types, functions and enums to be properly scoped inside or outside namespaces. But while integrating the 1.0.1 release in Ruby, I noticed that by mistake I forgot to properly configure the renaming for `Vec_U8`, which resulted in two copies of `Vec_U8` being emitted in the header files: `ddog_Vec_U8` and `ddof_prof_Vec_U8`, with some APIs using one and others using the other. This PR fixes the configuration. **Motivation**: Having two copies of the same struct is not correct and is really annoying for clients as well -- I temporarily needed to duplicate a helper on the Ruby profiler to have variants for both types (since often we don't even use a pointer but the struct directly, you can't even cast between them). **Additional Notes**: Here's the diff for the generated headers before/after this change: ```diff diff -uwr old-include/datadog/common.h build-linux/x86_64-linux/include/datadog/common.h --- old-include/datadog/common.h 2023-01-06 10:57:32.730644531 +0000 +++ build-linux/x86_64-linux/include/datadog/common.h 2023-01-06 10:58:41.954571430 +0000 @@ -106,16 +106,6 @@ */ typedef struct ddog_prof_Exporter_Request ddog_prof_Exporter_Request; -/** - * Holds the raw parts of a Rust Vec; it should only be created from Rust, - * never from C. - */ -typedef struct ddog_prof_Vec_U8 { - const uint8_t *ptr; - uintptr_t len; - uintptr_t capacity; -} ddog_prof_Vec_U8; - typedef enum ddog_prof_Exporter_NewResult_Tag { DDOG_PROF_EXPORTER_NEW_RESULT_OK, DDOG_PROF_EXPORTER_NEW_RESULT_ERR, @@ -128,7 +118,7 @@ struct ddog_prof_Exporter *ok; }; struct { - struct ddog_prof_Vec_U8 err; + struct ddog_Vec_U8 err; }; }; } ddog_prof_Exporter_NewResult; @@ -205,7 +195,7 @@ struct ddog_HttpStatus http_response; }; struct { - struct ddog_prof_Vec_U8 err; + struct ddog_Vec_U8 err; }; }; } ddog_prof_Exporter_SendResult; @@ -399,7 +389,7 @@ typedef struct ddog_prof_EncodedProfile { struct ddog_Timespec start; struct ddog_Timespec end; - struct ddog_prof_Vec_U8 buffer; + struct ddog_Vec_U8 buffer; struct ddog_prof_ProfiledEndpointsStats *endpoints_stats; } ddog_prof_EncodedProfile; @@ -415,7 +405,7 @@ struct ddog_prof_EncodedProfile ok; }; struct { - struct ddog_prof_Vec_U8 err; + struct ddog_Vec_U8 err; }; }; } ddog_prof_Profile_SerializeResult; diff -uwr old-include/datadog/profiling.h build-linux/x86_64-linux/include/datadog/profiling.h --- old-include/datadog/profiling.h 2023-01-06 10:57:32.730644531 +0000 +++ build-linux/x86_64-linux/include/datadog/profiling.h 2023-01-06 10:58:41.954571430 +0000 @@ -224,7 +224,7 @@ void ddog_prof_Profile_SerializeResult_drop(struct ddog_prof_Profile_SerializeResult _result); -DDOG_CHECK_RETURN struct ddog_Slice_U8 ddog_Vec_U8_as_slice(const struct ddog_prof_Vec_U8 *vec); +DDOG_CHECK_RETURN struct ddog_Slice_U8 ddog_Vec_U8_as_slice(const struct ddog_Vec_U8 *vec); /** * Resets all data in `profile` except the sample types and period. Returns ``` This is technically a breaking change for users of the C bindings, since a type gets removed (even if the type was never supposed to have existed). Since #80 is already bumping the libdatadog version to 2.0.0, I suggest only merging this PR after that one, and including it in the 2.0.0 release. **How to test the change?**: This change doesn't actually affect the compiled library, only the header files. Thus, the only way of noticing and testing this change, is to compile something that includes the headers and validate that only `ddog_Vec_U8` gets used.
ivoanjo
added a commit
that referenced
this pull request
Jan 11, 2023
**What does this PR do?**: In #73, we changed a number of types, functions and enums to be properly scoped inside or outside namespaces. But while integrating the 1.0.1 release in Ruby, I noticed that by mistake I forgot to properly configure the renaming for `Vec_U8`, which resulted in two copies of `Vec_U8` being emitted in the header files: `ddog_Vec_U8` and `ddof_prof_Vec_U8`, with some APIs using one and others using the other. This PR fixes the configuration. **Motivation**: Having two copies of the same struct is not correct and is really annoying for clients as well -- I temporarily needed to duplicate a helper on the Ruby profiler to have variants for both types (since often we don't even use a pointer but the struct directly, you can't even cast between them). **Additional Notes**: Here's the diff for the generated headers before/after this change: ```diff diff -uwr old-include/datadog/common.h build-linux/x86_64-linux/include/datadog/common.h --- old-include/datadog/common.h 2023-01-06 10:57:32.730644531 +0000 +++ build-linux/x86_64-linux/include/datadog/common.h 2023-01-06 10:58:41.954571430 +0000 @@ -106,16 +106,6 @@ */ typedef struct ddog_prof_Exporter_Request ddog_prof_Exporter_Request; -/** - * Holds the raw parts of a Rust Vec; it should only be created from Rust, - * never from C. - */ -typedef struct ddog_prof_Vec_U8 { - const uint8_t *ptr; - uintptr_t len; - uintptr_t capacity; -} ddog_prof_Vec_U8; - typedef enum ddog_prof_Exporter_NewResult_Tag { DDOG_PROF_EXPORTER_NEW_RESULT_OK, DDOG_PROF_EXPORTER_NEW_RESULT_ERR, @@ -128,7 +118,7 @@ struct ddog_prof_Exporter *ok; }; struct { - struct ddog_prof_Vec_U8 err; + struct ddog_Vec_U8 err; }; }; } ddog_prof_Exporter_NewResult; @@ -205,7 +195,7 @@ struct ddog_HttpStatus http_response; }; struct { - struct ddog_prof_Vec_U8 err; + struct ddog_Vec_U8 err; }; }; } ddog_prof_Exporter_SendResult; @@ -399,7 +389,7 @@ typedef struct ddog_prof_EncodedProfile { struct ddog_Timespec start; struct ddog_Timespec end; - struct ddog_prof_Vec_U8 buffer; + struct ddog_Vec_U8 buffer; struct ddog_prof_ProfiledEndpointsStats *endpoints_stats; } ddog_prof_EncodedProfile; @@ -415,7 +405,7 @@ struct ddog_prof_EncodedProfile ok; }; struct { - struct ddog_prof_Vec_U8 err; + struct ddog_Vec_U8 err; }; }; } ddog_prof_Profile_SerializeResult; diff -uwr old-include/datadog/profiling.h build-linux/x86_64-linux/include/datadog/profiling.h --- old-include/datadog/profiling.h 2023-01-06 10:57:32.730644531 +0000 +++ build-linux/x86_64-linux/include/datadog/profiling.h 2023-01-06 10:58:41.954571430 +0000 @@ -224,7 +224,7 @@ void ddog_prof_Profile_SerializeResult_drop(struct ddog_prof_Profile_SerializeResult _result); -DDOG_CHECK_RETURN struct ddog_Slice_U8 ddog_Vec_U8_as_slice(const struct ddog_prof_Vec_U8 *vec); +DDOG_CHECK_RETURN struct ddog_Slice_U8 ddog_Vec_U8_as_slice(const struct ddog_Vec_U8 *vec); /** * Resets all data in `profile` except the sample types and period. Returns ``` This is technically a breaking change for users of the C bindings, since a type gets removed (even if the type was never supposed to have existed). Since #80 is already bumping the libdatadog version to 2.0.0, I suggest only merging this PR after that one, and including it in the 2.0.0 release. **How to test the change?**: This change doesn't actually affect the compiled library, only the header files. Thus, the only way of noticing and testing this change, is to compile something that includes the headers and validate that only `ddog_Vec_U8` gets used. Co-authored-by: Levi Morrison <levi.morrison@datadoghq.com>
2 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What does this PR do?
This PR updates the names used in the libdatadog API as discussed in the 1.0 discussion meeting.
In particular, the following concerns were addressed:
Namespace names --
ddog_for common-ffi,ddog_prof_for profiling-ffi. This avoids having something likeddog_Linewhich is very specific to profiling be at the top of the namespace.Fixed inconsistency in destructors: we had
free,deleteanddrop. We now usedropeverywhere.Updated namespacing for nested things. E.g. the result of
ddog_prof_Exporter_newis addog_prof_Exporter_NewResult.Used case to separate structs (CamelCase) from methods (snake_case)
One departure from what was discussed in the meeting is how containers/generics are named. I had proposed
ddog_VecTagandddog_SliceU8but cbindgen really doesn't like it. Rather than fight cbindigen about it, I settled forddog_Vec_tagandddog_Slice_U8. Hopefully that is acceptable.Motivation
As our API grows, having a more consistent naming will hopefully help people navigate it. We still have a bit of a weird mix of what goes on
common.hvsprofiling.h, but I'll leave changing that for a later PR.Furthermore, it looked to me like 0.9-to-1.0 was a good time to address these concerns.
Additional Notes
To the best of my knowledge, here's the complete list of all types changed:
How to test the change?
The ffi example apps have been updated and should still compile/work fine.
Profilers using libdatadog will need to be updated to use the new names, but otherwise should remain working as before.