lib: add internal object pool API and use it; adapt plugins/tests

[babeltrace.git] / include / babeltrace / ctf-ir / packet.h

diff --git a/include/babeltrace/ctf-ir/packet.h b/include/babeltrace/ctf-ir/packet.h
index 40aaab1583544b2b2bc95fb91d392910ec5f882a..e87a5f806dc86cf23553dcd05c993c66a1706758 100644 (file)
--- a/include/babeltrace/ctf-ir/packet.h
+++ b/include/babeltrace/ctf-ir/packet.h
@@ -28,32 +28,146 @@
  * http://www.efficios.com/ctf
  */
 
+/* For bt_get() */
+#include <babeltrace/ref.h>
+
 #include <stdint.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-struct bt_ctf_stream;
-struct bt_ctf_packet;
+/**
+@defgroup ctfirpacket CTF IR packet
+@ingroup ctfir
+@brief CTF IR packet.
+
+@code
+#include <babeltrace/ctf-ir/packet.h>
+@endcode
+
+A CTF IR <strong><em>packet</em></strong> is a container of packet
+fields, that is, of the <strong>trace packet header</strong> and
+<strong>stream packet context</strong> fields.
+
+As a reminder, here's the structure of a CTF packet:
+
+@imgpacketstructure
+
+You can create a CTF IR packet \em from a
+\link ctfirstream CTF IR stream\endlink with bt_packet_create(). The
+stream you use to create a packet object becomes its parent.
+
+When you set the trace packet header and stream packet context fields of
+a packet with resp. bt_packet_set_header() and
+bt_packet_set_context(), their field type \em must be equivalent to
+the field types returned by resp. bt_trace_get_packet_header_type()
+and bt_stream_class_get_packet_context_type() for its parent trace
+class and stream class.
+
+You can attach a packet object to a \link ctfirevent CTF IR
+event\endlink object with bt_event_set_packet().
+
+As with any Babeltrace object, CTF IR packet objects have
+<a href="https://en.wikipedia.org/wiki/Reference_counting">reference
+counts</a>. See \ref refs to learn more about the reference counting
+management of Babeltrace objects.
+
+bt_notification_event_create() \em freezes its event parameter on
+success, which in turns freezes the event's associated packet object.
+This is the only way that a CTF IR packet object can be frozen.
+You cannot modify a frozen packet: it is considered immutable,
+except for \link refs reference counting\endlink.
+
+@sa ctfirstream
+@sa ctfirstreamclass
+@sa ctfirtraceclass
+
+@file
+@brief CTF IR packet type and functions.
+@sa ctfirpacket
+
+@addtogroup ctfirpacket
+@{
+*/
+
+/**
+@struct bt_packet
+@brief A CTF IR packet.
+@sa ctfirpacket
+*/
+struct bt_packet;
+struct bt_packet_header_field;
+struct bt_packet_context_field;
+struct bt_stream;
+
+/**
+@name Creation and parent access functions
+@{
+*/
+
+/**
+@brief Creates a default CTF IR packet with \p stream as its parent
+       CTF IR stream.
+
+On success, the packet object's trace packet header and stream packet
+context fields are not set. You can set them with resp.
+bt_packet_set_header() and bt_packet_set_context().
+
+@param[in] stream      Parent CTF IR stream of the packet to create.
+@returns               Created packet, or \c NULL on error.
+
+@prenotnull{stream}
+@postsuccessrefcountret1
+*/
+extern struct bt_packet *bt_packet_create(struct bt_stream *stream);
+
+extern struct bt_stream *bt_packet_borrow_stream(struct bt_packet *packet);
+
+/**
+@brief Returns the parent CTF IR stream of the CTF IR packet \p packet.
+
+This function returns a reference to the stream which was used to create
+the packet object in the first place with bt_packet_create().
+
+@param[in] packet      Packet of which to get the parent stream.
+@returns               Parent stream of \p packet, or \c NULL on error.
+
+@prenotnull{packet}
+@postrefcountsame{packet}
+@postsuccessrefcountretinc
+*/
+static inline
+struct bt_stream *bt_packet_get_stream(
+               struct bt_packet *packet)
+{
+       return bt_get(bt_packet_borrow_stream(packet));
+}
+
+/** @} */
+
+/**
+@name Contained fields functions
+@{
+*/
 
-extern struct bt_ctf_packet *bt_ctf_packet_create(
-               struct bt_ctf_stream *stream);
+extern
+struct bt_field *bt_packet_borrow_header(struct bt_packet *packet);
 
-extern struct bt_ctf_stream *bt_ctf_packet_get_stream(
-               struct bt_ctf_packet *packet);
+extern
+int bt_packet_move_header(struct bt_packet *packet,
+               struct bt_packet_header_field *header);
 
-extern struct bt_ctf_field *bt_ctf_packet_get_header(
-               struct bt_ctf_packet *packet);
+extern
+struct bt_field *bt_packet_borrow_context(struct bt_packet *packet);
 
-extern int bt_ctf_packet_set_header(
-               struct bt_ctf_packet *packet, struct bt_ctf_field *header);
+extern
+int bt_packet_move_context(struct bt_packet *packet,
+               struct bt_packet_context_field *context);
 
-extern struct bt_ctf_field *bt_ctf_packet_get_context(
-               struct bt_ctf_packet *context);
+/** @} */
 
-extern int bt_ctf_packet_set_context(
-               struct bt_ctf_packet *packet, struct bt_ctf_field *context);
+/** @} */
 
 #ifdef __cplusplus
 }