From 0a70dd28a1c8594c14c2263eff0c8c5010d851c1 Mon Sep 17 00:00:00 2001 From: Florian Reimold <11774314+FlorianReimold@users.noreply.github.com> Date: Tue, 5 Mar 2024 11:32:38 +0100 Subject: [PATCH 1/3] Added empty deprecation document --- doc/rst/versions/5.13/compatibility_table.txt | 4 ++++ doc/rst/versions/5.13/deprecation.rst | 7 +++++++ doc/rst/versions/5.13/whats_new.rst | 1 - 3 files changed, 11 insertions(+), 1 deletion(-) create mode 100644 doc/rst/versions/5.13/deprecation.rst diff --git a/doc/rst/versions/5.13/compatibility_table.txt b/doc/rst/versions/5.13/compatibility_table.txt index 038b8041ac..e42764e967 100644 --- a/doc/rst/versions/5.13/compatibility_table.txt +++ b/doc/rst/versions/5.13/compatibility_table.txt @@ -24,6 +24,10 @@ - * **API**: downwards compatible. + A lot of deprecations were added. + Users should make sure to only use non-deprecated API and files in order to later make upgrading to eCAL 6 easier. + Deprecations can be found :ref:`in this document ` + * **ABI**: not compatible * - Tools diff --git a/doc/rst/versions/5.13/deprecation.rst b/doc/rst/versions/5.13/deprecation.rst new file mode 100644 index 0000000000..f3469197d6 --- /dev/null +++ b/doc/rst/versions/5.13/deprecation.rst @@ -0,0 +1,7 @@ +:orphan: + +.. _compatibility_details_5_13_deprecations: + +====================== +eCAL 5.13 Deprecations +====================== \ No newline at end of file diff --git a/doc/rst/versions/5.13/whats_new.rst b/doc/rst/versions/5.13/whats_new.rst index c0dbf20e5d..62df8fee57 100644 --- a/doc/rst/versions/5.13/whats_new.rst +++ b/doc/rst/versions/5.13/whats_new.rst @@ -14,7 +14,6 @@ eCAL 5.13 was released in March 2024. New features ============ - - Check out the `entire 5.13.0 changelog `_!. Compatibility table From 1c4b3a0452a5261b9c7b6019340b58c5a4beb632 Mon Sep 17 00:00:00 2001 From: Peter Guenschmann <73380451+Peguen@users.noreply.github.com> Date: Mon, 11 Mar 2024 12:15:01 +0100 Subject: [PATCH 2/3] Added deprecation documentation --- doc/rst/versions/5.13/deprecation.rst | 229 +++++++++++++++++++++++++- 1 file changed, 228 insertions(+), 1 deletion(-) diff --git a/doc/rst/versions/5.13/deprecation.rst b/doc/rst/versions/5.13/deprecation.rst index f3469197d6..35c73992df 100644 --- a/doc/rst/versions/5.13/deprecation.rst +++ b/doc/rst/versions/5.13/deprecation.rst @@ -4,4 +4,231 @@ ====================== eCAL 5.13 Deprecations -====================== \ No newline at end of file +====================== + +All API functions (C & C++) deprecated that are no longer part of the +future eCAL6 API. + +Deprecated header files +======================= + +- :file:`/ecal/cimpl/ecal_event_cimpl.h` +- :file:`include/ecal/cimpl/ecal_proto_dyn_json_subscriber_cimpl.h` +- :file:`include/ecal/cimpl/ecal_qos_cimpl.h` +- :file:`include/ecal/ecal_clang.h` +- :file:`include/ecal/ecal_event.h` +- :file:`include/ecal/ecal_eventhandle.h` +- :file:`include/ecal/ecal_qos.h` +- :file:`include/ecal/ecal_timed_cb.h` + +Deprecated API +============== + +- :file:`ecal_callback_cimpl.h`: + + .. code-block:: cpp + + enum eCAL_Subscriber_Event + { + sub_event_none = 0, + sub_event_connected = 1, + sub_event_disconnected = 2, + sub_event_dropped = 3, + sub_event_timeout = 4, //!< deprecated, will be removed in future eCAL versions + sub_event_corrupted = 5, + sub_event_update_connection = 6, + }; + + struct SPubEventCallbackDataC + { + enum eCAL_Publisher_Event type; //!< event type + long long time; //!< event time stamp + long long clock; //!< event clock + const char* tid; //!< topic id of the connected subscriber (for pub_event_update_connection only) + const char* tname; //!< topic type encoding of the connected subscriber (for pub_event_update_connection only) + const char* tencoding; //!< topic type name of the connected subscriber (for pub_event_update_connection only) + const char* tdesc; //!< topic type descriptor information of the connected subscriber (for pub_event_update_connection only) + + const char* ttype; //!< deprecated, please use new tname + tencoding fields + }; + + struct SSubEventCallbackDataC + { + enum eCAL_Subscriber_Event type; //!< event type + long long time; //!< event time stamp + long long clock; //!< event clock + const char* tid; //!< topic id of the connected publisher (for sub_event_update_connection only) + const char* tname; //!< topic type encoding of the connected publisher (for sub_event_update_connection only) + const char* tencoding; //!< topic type name of the connected publisher (for sub_event_update_connection only) + const char* tdesc; //!< topic type descriptor information of the connected publisher (for sub_event_update_connection only) + + const char* ttype; //!< deprecated, please use new tname + tencoding fields + }; + +- :file:`ecal_client_cimpl.h`: + + .. code-block:: cpp + + int eCAL_Client_AddResponseCallbackC(ECAL_HANDLE handle_, ResponseCallbackCT callback_, void* par_); + +- :file:`ecal_init_cimpl.h`: + + .. code-block:: cpp + + #define eCAL_Init_Publisher 0x01 /*!< Initialize Publisher API */ + #define eCAL_Init_Subscriber 0x02 /*!< Initialize Subscriber API */ + #define eCAL_Init_Service 0x04 /*!< Initialize Service API */ + #define eCAL_Init_Monitoring 0x08 /*!< Initialize Monitoring API */ + #define eCAL_Init_Logging 0x10 /*!< Initialize Logging API */ + #define eCAL_Init_TimeSync 0x20 /*!< Initialize Time API */ + #define eCAL_Init_RPC 0x40 /*!< deprecated, will be removed in future eCAL versions */ + #define eCAL_Init_ProcessReg 0x80 /*!< Initialize Process Registration API */ + +- :file:`ecal_log_cimpl.h`: + + .. code-block:: cpp + + void eCAL_Logging_StartCoreTimer(); + void eCAL_Logging_StopCoreTimer(); + void eCAL_Logging_SetCoreTime(double time_); + double eCAL_Logging_GetCoreTime(); + +- :file:`ecal_process_cimpl.h`: + + .. code-block:: cpp + + int eCAL_Process_GetHostID(); + float eCAL_Process_GetProcessCpuUsage(); + unsigned long eCAL_Process_GetProcessMemory(); + long long eCAL_Process_GetSClock(); + long long eCAL_Process_GetSBytes(); + long long eCAL_Process_GetWClock(); + long long eCAL_Process_GetWBytes(); + long long eCAL_Process_GetRClock(); + long long eCAL_Process_GetRBytes(); + +- :file:`ecal_publisher_cimpl.h`: + + .. code-block:: cpp + + int eCAL_Pub_SetQOS(ECAL_HANDLE handle_, struct SWriterQOSC qos_); + int eCAL_Pub_GetQOS(ECAL_HANDLE handle_, struct SWriterQOSC* qos_); + int eCAL_Pub_SetMaxBandwidthUDP(ECAL_HANDLE handle_, long bandwidth_); + +- :file:`ecal_server_cimpl.h`: + + .. code-block:: cpp + + int eCAL_Server_AddMethodCallbackC(ECAL_HANDLE handle_, const char* method_, const char* req_type_, const char* resp_type_, MethodCallbackCT callback_, void* par_); + int eCAL_Server_RemMethodCallbackC(ECAL_HANDLE handle_, const char* method_); + +- :file:`ecal_subscriber_cimpl.h`: + + .. code-block:: cpp + + int eCAL_Sub_SetQOS(ECAL_HANDLE handle_, struct SReaderQOSC qos_); + int eCAL_Sub_GetQOS(ECAL_HANDLE handle_, struct SReaderQOSC* qos_); + int eCAL_Sub_SetTimeout(ECAL_HANDLE handle_, int timeout_); + +- :file:`ecal_tlayer_cimpl.h`: + + .. code-block:: cpp + + enum eTransportLayerC + { + tlayer_none = 0, + tlayer_udp_mc = 1, + tlayer_shm = 4, + tlayer_tcp = 5, + tlayer_inproc = 42, /*!< deprecated, whole layer will be removed in future eCAL versions */ + tlayer_all = 255 + }; + +- :file:`ecal_log.h`: + + .. code-block:: cpp + + void StartCoreTimer(); + void StopCoreTimer(); + void SetCoreTime(double time_); + double GetCoreTime(); + +- :file:`ecal_monitoring.h`: + + .. code-block:: cpp + + int GetMonitoring(std::string& mon_); + +- :file:`ecal_process.h`: + + .. code-block:: cpp + + int GetHostID(); + float GetProcessCpuUsage(); + unsigned long GetProcessMemory(); + long long GetWClock(); + long long GetWBytes(); + long long GetRClock(); + long long GetRBytes(); + +- :file:`ecal_publisher.h`: + + .. code-block:: cpp + + bool SetQOS(const QOS::SWriterQOS& qos_); + QOS::SWriterQOS GetQOS(); + bool SetMaxBandwidthUDP(long bandwidth_); + +- :file:`ecal_subscriber.h`: + + .. code-block:: cpp + + bool SetQOS(const QOS::SReaderQOS& qos_); + QOS::SReaderQOS GetQOS(); + bool SetTimeout(int timeout_); + +- :file:`ecal_tlayer.h`: + + .. code-block:: cpp + + enum eTransportLayer + { + tlayer_none = 0, + tlayer_udp_mc = 1, + tlayer_shm = 4, + tlayer_tcp = 5, + tlayer_inproc = 42, //!< deprecated, whole layer will be removed in future eCAL versions + tlayer_all = 255 + }; + + struct ECAL_API STLayer + { + STLayer() + { + sm_udp_mc = smode_none; + sm_shm = smode_none; + sm_inproc = smode_none; + sm_tcp = smode_none; + } + eSendMode sm_udp_mc; //!< udp multicast + eSendMode sm_shm; //!< shared memory + eSendMode sm_inproc; //!< deprecated, whole layer will be removed in future eCAL versions */ + eSendMode sm_tcp; //!< tcp + }; + +Added API +========= + +- :file:`ecal_subscriber_cimpl.h`: + + .. code-block:: cpp + + ECALC_API int eCAL_Sub_GetTypeName(ECAL_HANDLE handle_, void* buf_, int buf_len_); + ECALC_API int eCAL_Sub_GetEncoding(ECAL_HANDLE handle_, void* buf_, int buf_len_); + +- :file:`ecal_util_cimpl.h`: + + .. code-block:: cpp + + ECALC_API int eCAL_Util_GetTopicEncoding(const char* topic_name_, void* topic_encoding_, int topic_encoding_len_); + ECALC_API int eCAL_Util_GetTopicDescription(const char* topic_name_, void* topic_desc_, int topic_desc_len_); From 50127ed97c9bc283bfae21ec8419ec67d1a07e1e Mon Sep 17 00:00:00 2001 From: tftzee <49162693+rex-schilasky@users.noreply.github.com> Date: Wed, 13 Mar 2024 14:25:45 +0100 Subject: [PATCH 3/3] deprecation doc completed --- doc/rst/versions/5.13/deprecation.rst | 177 +++++++++++++++++++------- 1 file changed, 133 insertions(+), 44 deletions(-) diff --git a/doc/rst/versions/5.13/deprecation.rst b/doc/rst/versions/5.13/deprecation.rst index 35c73992df..648e7e115a 100644 --- a/doc/rst/versions/5.13/deprecation.rst +++ b/doc/rst/versions/5.13/deprecation.rst @@ -12,19 +12,19 @@ future eCAL6 API. Deprecated header files ======================= -- :file:`/ecal/cimpl/ecal_event_cimpl.h` -- :file:`include/ecal/cimpl/ecal_proto_dyn_json_subscriber_cimpl.h` -- :file:`include/ecal/cimpl/ecal_qos_cimpl.h` -- :file:`include/ecal/ecal_clang.h` -- :file:`include/ecal/ecal_event.h` -- :file:`include/ecal/ecal_eventhandle.h` -- :file:`include/ecal/ecal_qos.h` -- :file:`include/ecal/ecal_timed_cb.h` +- :file:`cimpl/ecal_event_cimpl.h` +- :file:`cimpl/ecal_proto_dyn_json_subscriber_cimpl.h` +- :file:`cimpl/ecal_qos_cimpl.h` +- :file:`ecal_clang.h` +- :file:`ecal_event.h` +- :file:`ecal_eventhandle.h` +- :file:`ecal_qos.h` +- :file:`ecal_timed_cb.h` Deprecated API ============== -- :file:`ecal_callback_cimpl.h`: +- :file:`cimpl/ecal_callback_cimpl.h`: .. code-block:: cpp @@ -34,57 +34,57 @@ Deprecated API sub_event_connected = 1, sub_event_disconnected = 2, sub_event_dropped = 3, - sub_event_timeout = 4, //!< deprecated, will be removed in future eCAL versions + sub_event_timeout = 4, //!< deprecated, will be removed in future eCAL versions sub_event_corrupted = 5, sub_event_update_connection = 6, }; struct SPubEventCallbackDataC { - enum eCAL_Publisher_Event type; //!< event type - long long time; //!< event time stamp - long long clock; //!< event clock - const char* tid; //!< topic id of the connected subscriber (for pub_event_update_connection only) - const char* tname; //!< topic type encoding of the connected subscriber (for pub_event_update_connection only) - const char* tencoding; //!< topic type name of the connected subscriber (for pub_event_update_connection only) - const char* tdesc; //!< topic type descriptor information of the connected subscriber (for pub_event_update_connection only) + enum eCAL_Publisher_Event type; + long long time; + long long clock; + const char* tid; + const char* tname; + const char* tencoding; + const char* tdesc; const char* ttype; //!< deprecated, please use new tname + tencoding fields }; struct SSubEventCallbackDataC { - enum eCAL_Subscriber_Event type; //!< event type - long long time; //!< event time stamp - long long clock; //!< event clock - const char* tid; //!< topic id of the connected publisher (for sub_event_update_connection only) - const char* tname; //!< topic type encoding of the connected publisher (for sub_event_update_connection only) - const char* tencoding; //!< topic type name of the connected publisher (for sub_event_update_connection only) - const char* tdesc; //!< topic type descriptor information of the connected publisher (for sub_event_update_connection only) + enum eCAL_Subscriber_Event type; + long long time; + long long clock; + const char* tid; + const char* tname; + const char* tencoding; + const char* tdesc; const char* ttype; //!< deprecated, please use new tname + tencoding fields }; -- :file:`ecal_client_cimpl.h`: +- :file:`cimpl/ecal_client_cimpl.h`: .. code-block:: cpp int eCAL_Client_AddResponseCallbackC(ECAL_HANDLE handle_, ResponseCallbackCT callback_, void* par_); -- :file:`ecal_init_cimpl.h`: +- :file:`cimpl/ecal_init_cimpl.h`: .. code-block:: cpp - #define eCAL_Init_Publisher 0x01 /*!< Initialize Publisher API */ - #define eCAL_Init_Subscriber 0x02 /*!< Initialize Subscriber API */ - #define eCAL_Init_Service 0x04 /*!< Initialize Service API */ - #define eCAL_Init_Monitoring 0x08 /*!< Initialize Monitoring API */ - #define eCAL_Init_Logging 0x10 /*!< Initialize Logging API */ - #define eCAL_Init_TimeSync 0x20 /*!< Initialize Time API */ - #define eCAL_Init_RPC 0x40 /*!< deprecated, will be removed in future eCAL versions */ - #define eCAL_Init_ProcessReg 0x80 /*!< Initialize Process Registration API */ + #define eCAL_Init_Publisher 0x01 + #define eCAL_Init_Subscriber 0x02 + #define eCAL_Init_Service 0x04 + #define eCAL_Init_Monitoring 0x08 + #define eCAL_Init_Logging 0x10 + #define eCAL_Init_TimeSync 0x20 + #define eCAL_Init_RPC 0x40 /*!< deprecated, will be removed in future eCAL versions */ + #define eCAL_Init_ProcessReg 0x80 -- :file:`ecal_log_cimpl.h`: +- :file:`cimpl/ecal_log_cimpl.h`: .. code-block:: cpp @@ -93,7 +93,12 @@ Deprecated API void eCAL_Logging_SetCoreTime(double time_); double eCAL_Logging_GetCoreTime(); -- :file:`ecal_process_cimpl.h`: +- :file:`cimpl/ecal_monitoring_cimpl.h`: + + int eCAL_Monitoring_PubMonitoring(int state_, const char* name_); + int eCAL_Monitoring_PubLogging(int state_, const char* name_); + +- :file:`cimpl/ecal_process_cimpl.h`: .. code-block:: cpp @@ -107,7 +112,7 @@ Deprecated API long long eCAL_Process_GetRClock(); long long eCAL_Process_GetRBytes(); -- :file:`ecal_publisher_cimpl.h`: +- :file:`cimpl/ecal_publisher_cimpl.h`: .. code-block:: cpp @@ -115,14 +120,14 @@ Deprecated API int eCAL_Pub_GetQOS(ECAL_HANDLE handle_, struct SWriterQOSC* qos_); int eCAL_Pub_SetMaxBandwidthUDP(ECAL_HANDLE handle_, long bandwidth_); -- :file:`ecal_server_cimpl.h`: +- :file:`cimpl/ecal_server_cimpl.h`: .. code-block:: cpp int eCAL_Server_AddMethodCallbackC(ECAL_HANDLE handle_, const char* method_, const char* req_type_, const char* resp_type_, MethodCallbackCT callback_, void* par_); int eCAL_Server_RemMethodCallbackC(ECAL_HANDLE handle_, const char* method_); -- :file:`ecal_subscriber_cimpl.h`: +- :file:`cimpl/ecal_subscriber_cimpl.h`: .. code-block:: cpp @@ -130,7 +135,7 @@ Deprecated API int eCAL_Sub_GetQOS(ECAL_HANDLE handle_, struct SReaderQOSC* qos_); int eCAL_Sub_SetTimeout(ECAL_HANDLE handle_, int timeout_); -- :file:`ecal_tlayer_cimpl.h`: +- :file:`cimpl/ecal_tlayer_cimpl.h`: .. code-block:: cpp @@ -144,6 +149,39 @@ Deprecated API tlayer_all = 255 }; +- :file:`cimpl/ecal_util_cimpl.h`: + + .. code-block:: cpp + + int eCAL_Util_GetTypeName(const char* topic_name_, void* topic_type_, int topic_type_len_); + int eCAL_Util_GetDescription(const char* topic_name_, void* topic_desc_, int topic_desc_len_); + +- :file:`ecal_callback.h`: + + struct SPubEventCallbackData + { + eCAL_Publisher_Event type; + long long time; + long long clock; + std::string tid; + std::string ttype; //!< deprecated, please use new tdatatype field + std::string tdesc; //!< deprecated, please use new tdatatype field + + SDataTypeInformation tdatatype; + }; + + struct SSubEventCallbackData + { + eCAL_Subscriber_Event type; + long long time; + long long clock; + std::string tid; + std::string ttype; //!< deprecated, please use new tdatatype field + std::string tdesc; //!< deprecated, please use new tdatatype field + + SDataTypeInformation tdatatype; + }; + - :file:`ecal_log.h`: .. code-block:: cpp @@ -158,6 +196,8 @@ Deprecated API .. code-block:: cpp int GetMonitoring(std::string& mon_); + int PubMonitoring(bool state_, std::string name_ = "ecal.monitoring"); + int PubLogging(bool state_, std::string name_ = "ecal.logging"); - :file:`ecal_process.h`: @@ -175,16 +215,26 @@ Deprecated API .. code-block:: cpp + CPublisher(const std::string& topic_name_, const std::string& topic_type_, const std::string& topic_desc_ = ""); + bool Create(const std::string& topic_name_, const std::string& topic_type_, const std::string& topic_desc_ = ""); + bool SetTypeName(const std::string& topic_type_name_); + bool SetDescription(const std::string& topic_desc_); bool SetQOS(const QOS::SWriterQOS& qos_); QOS::SWriterQOS GetQOS(); bool SetMaxBandwidthUDP(long bandwidth_); + std::string GetTypeName() const; + std::string GetDescription() const; - :file:`ecal_subscriber.h`: .. code-block:: cpp + CSubscriber(const std::string& topic_name_, const std::string& topic_type_, const std::string& topic_desc_ = ""); + bool Create(const std::string& topic_name_, const std::string& topic_type_, const std::string& topic_desc_ = ""); bool SetQOS(const QOS::SReaderQOS& qos_); QOS::SReaderQOS GetQOS(); + std::string GetTypeName() const; + std::string GetDescription() const; bool SetTimeout(int timeout_); - :file:`ecal_tlayer.h`: @@ -210,12 +260,51 @@ Deprecated API sm_inproc = smode_none; sm_tcp = smode_none; } - eSendMode sm_udp_mc; //!< udp multicast - eSendMode sm_shm; //!< shared memory + eSendMode sm_udp_mc; + eSendMode sm_shm; eSendMode sm_inproc; //!< deprecated, whole layer will be removed in future eCAL versions */ - eSendMode sm_tcp; //!< tcp + eSendMode sm_tcp; }; - + +- :file:`ecal_util.h`: + + bool GetTopicTypeName(const std::string& topic_name_, std::string& topic_type_); + std::string GetTopicTypeName(const std::string& topic_name_); + bool GetTopicDescription(const std::string& topic_name_, std::string& topic_desc_); + std::string GetTopicDescription(const std::string& topic_name_); + std::string GetDescription(const std::string& topic_name_); + +- :file:`msg/capnproto/dynamic.h`: + + std::string GetTypeName() const; + +- :file:`msg/capnproto/subscriber.h`: + + std::string GetTypeName() const; + +- :file:`msg/protobuf/publisher.h`: + + std::string GetTypeName() const; + std::string GetDescription() const; + +- :file:`msg/string/publisher.h`: + + CPublisher(const std::string& topic_name_, const std::string& topic_type_, const std::string& topic_desc_); + +- :file:`msg/publisher.h`: + + CMsgPublisher(const std::string& topic_name_, const std::string& topic_type_, const std::string& topic_desc_ = ""); + bool Create(const std::string& topic_name_, const std::string& topic_type_ = "", const std::string& topic_desc_ = ""); + virtual std::string GetTypeName() const; + virtual std::string GetDescription() const; + +- :file:`msg/subscriber.h`: + + CMsgSubscriber(const std::string& topic_name_, const std::string& topic_type_ = "", const std::string& topic_desc_ = ""); + bool Create(const std::string& topic_name_, const std::string& topic_type_ = "", const std::string& topic_desc_ = "") + virtual std::string GetTypeName() const; + virtual std::string GetDescription() const; + Added API =========