diff --git a/mediapipe/framework/BUILD b/mediapipe/framework/BUILD index b31d390c..ca8b0057 100644 --- a/mediapipe/framework/BUILD +++ b/mediapipe/framework/BUILD @@ -895,6 +895,7 @@ cc_library( "@com_google_absl//absl/log:absl_check", "@com_google_absl//absl/log:absl_log", "@com_google_absl//absl/memory", + "@com_google_absl//absl/status:statusor", "@com_google_absl//absl/strings", "@com_google_absl//absl/synchronization", ], diff --git a/mediapipe/framework/packet.h b/mediapipe/framework/packet.h index 770dd9d4..84ae94dc 100644 --- a/mediapipe/framework/packet.h +++ b/mediapipe/framework/packet.h @@ -20,6 +20,7 @@ #include #include #include +#include #include #include @@ -27,6 +28,7 @@ #include "absl/log/absl_check.h" #include "absl/log/absl_log.h" #include "absl/memory/memory.h" +#include "absl/status/statusor.h" #include "absl/strings/str_cat.h" #include "absl/synchronization/mutex.h" #include "mediapipe/framework/deps/no_destructor.h" @@ -112,7 +114,18 @@ class Packet { // Transfers the ownership of holder's data to a unique pointer // of the object if the packet is the sole owner of a non-foreign // holder. Otherwise, returns error when the packet can't be consumed. - // See ConsumeOrCopy for threading requirements and example usage. + // + // --- WARNING --- + // Packet is thread-compatible and this member function is non-const. Hence, + // calling it requires exclusive access to the object - callers are + // responsible for ensuring that no other thread is doing anything with the + // packet. + // + // For example, if a node/calculator calls this function, then no other + // calculator should be processing the same packet. Nodes/calculators cannot + // enforce/guarantee this as they don't know of each other, which means graph + // must be written in a special way to account for that. It's error-prone and + // general recommendation is to avoid calling this function. template absl::StatusOr> Consume(); @@ -120,13 +133,22 @@ class Packet { // unique pointer if the packet is the sole owner of a non-foreign // holder. Otherwise, the unique pointer holds a copy of the original // data. In either case, the original packet is set to empty. The - // method returns error when the packet can't be consumed or copied. If + // function returns error when the packet can't be consumed or copied. If // was_copied is not nullptr, it is set to indicate whether the packet // data was copied. - // Packet is thread-compatible, therefore Packet::ConsumeOrCopy() - // must be thread-compatible: clients who use this function are - // responsible for ensuring that no other thread is doing anything - // with the Packet. + // + // --- WARNING --- + // Packet is thread-compatible and this member function is non-const. Hence, + // calling it requires exclusive access to the object - callers are + // responsible for ensuring that no other thread is doing anything with the + // packet. + // + // For example, if a node/calculator calls this function, then no other + // calculator should be processing the same packet. Nodes/calculators cannot + // enforce/guarantee this as they don't know of each other, which means graph + // must be written in a special way to account for that. It's error-prone and + // general recommendation is to avoid calling this function. + // // Example usage: // ASSIGN_OR_RETURN(std::unique_ptr detection, // p.ConsumeOrCopy());