Add sequence numbers to events and messages. See #559250.

Original commit message from CVS:
2008-11-04  Andy Wingo  <wingo@pobox.com>

Add sequence numbers to events and messages. See #559250.

* gst/gstutils.c (gst_util_seqnum_next, gst_util_seqnum_compare):
New functions.

* gst/gstevent.h:
* gst/gstevent.c (_gst_event_copy, gst_event_new): Initialize new
events with a new sequence number, and copy it when copying.
(gst_event_get_seqnum, gst_event_set_seqnum): Accessors for an
event's sequence number.

* gst/gstmessage.h:
* gst/gstmessage.c (_gst_message_copy, gst_message_new_custom):
(gst_event_get_seqnum, gst_event_set_seqnum): As with events, so
with messages.

* docs/gst/gstreamer-sections.txt: Add new functions to the docs.

ChangeLog

@@ -1,3 +1,18 @@
+2008-11-04  Andy Wingo  <wingo@pobox.com>
+
+	* gst/gstevent.h:
+	* gst/gstevent.c (_gst_event_copy, gst_event_new): Initialize new
+	events with a new sequence number, and copy it when copying.
+	(gst_event_get_seqnum, gst_event_set_seqnum): Accessors for an
+	event's sequence number.
+
+	* gst/gstmessage.h:
+	* gst/gstmessage.c (_gst_message_copy, gst_message_new_custom):
+	(gst_event_get_seqnum, gst_event_set_seqnum): As with events, so
+	with messages.
+
+	* docs/gst/gstreamer-sections.txt: Add new functions to the docs.
+
 2008-11-04  Wim Taymans  <wim.taymans@collabora.co.uk>
 
 	* docs/manual/advanced-position.xml:

docs/gst/gstreamer-sections.txt

@@ -665,6 +665,9 @@ gst_event_new_custom
 gst_event_get_structure
 gst_event_has_name
 
+gst_event_get_seqnum
+gst_event_set_seqnum
+
 gst_event_new_flush_start
 gst_event_new_flush_stop
 
@@ -1044,6 +1047,8 @@ gst_message_unref
 gst_message_copy
 gst_message_get_structure
 gst_message_make_writable
+gst_message_get_seqnum
+gst_message_set_seqnum
 
 gst_message_new_eos
 gst_message_new_error
@@ -2335,6 +2340,8 @@ gst_type_register_static_full
 gst_util_dump_mem
 gst_util_uint64_scale
 gst_util_uint64_scale_int
+gst_util_seqnum_next
+gst_util_seqnum_compare
 gst_util_set_object_arg
 gst_util_set_value_from_string
 gst_util_get_timestamp

gst/gstevent.c

@@ -85,6 +85,8 @@
 #include "gstutils.h"
 #include "gstquark.h"
 
+#define GST_EVENT_SEQNUM(e) ((GstEvent*)e)->abidata.seqnum
+
 static void gst_event_init (GTypeInstance * instance, gpointer g_class);
 static void gst_event_class_init (gpointer g_class, gpointer class_data);
 static void gst_event_finalize (GstEvent * event);
@@ -270,6 +272,7 @@ _gst_event_copy (GstEvent * event)
 
   GST_EVENT_TYPE (copy) = GST_EVENT_TYPE (event);
   GST_EVENT_TIMESTAMP (copy) = GST_EVENT_TIMESTAMP (event);
+  GST_EVENT_SEQNUM (copy) = GST_EVENT_SEQNUM (event);
 
   if (GST_EVENT_SRC (event)) {
     GST_EVENT_SRC (copy) = gst_object_ref (GST_EVENT_SRC (event));
@@ -295,6 +298,7 @@ gst_event_new (GstEventType type)
   event->type = type;
   event->src = NULL;
   event->structure = NULL;
+  GST_EVENT_SEQNUM (event) = gst_util_seqnum_next ();
 
   return event;
 }
@@ -378,6 +382,60 @@ gst_event_has_name (GstEvent * event, const gchar * name)
   return gst_structure_has_name (event->structure, name);
 }
 
+/**
+ * gst_event_get_seqnum:
+ * @event: A #GstEvent.
+ *
+ * Retrieve the sequence number of a event.
+ *
+ * Events have ever-incrementing sequence numbers, which may also be set
+ * explicitly via gst_event_set_seqnum(). Sequence numbers are typically used to
+ * indicate that a event corresponds to some other set of events or messages,
+ * for example an EOS event corresponding to a SEEK event. It is considered good
+ * practice to make this correspondence when possible, though it is not
+ * required.
+ *
+ * Note that events and messages share the same sequence number incrementor;
+ * two events or messages will never not have the same sequence number unless
+ * that correspondence was made explicitly.
+ *
+ * Returns: The event's sequence number.
+ *
+ * MT safe.
+ *
+ * Since: 0.10.22
+ */
+guint32
+gst_event_get_seqnum (GstEvent * event)
+{
+  g_return_val_if_fail (GST_IS_EVENT (event), -1);
+
+  return GST_EVENT_SEQNUM (event);
+}
+
+/**
+ * gst_event_set_seqnum:
+ * @event: A #GstEvent.
+ * @seqnum: A sequence number.
+ *
+ * Set the sequence number of a event.
+ *
+ * This function might be called by the creator of a event to indicate that the
+ * event relates to other events or messages. See gst_event_get_seqnum() for
+ * more information.
+ *
+ * MT safe.
+ *
+ * Since: 0.10.22
+ */
+void
+gst_event_set_seqnum (GstEvent * event, guint32 seqnum)
+{
+  g_return_if_fail (GST_IS_EVENT (event));
+
+  GST_EVENT_SEQNUM (event) = seqnum;
+}
+
 /**
  * gst_event_new_flush_start:
  *

gst/gstevent.h

@@ -305,7 +305,10 @@ struct _GstEvent {
   GstStructure	*structure;
 
   /*< private >*/
-  gpointer _gst_reserved;
+  union {
+    guint32 seqnum;
+    gpointer _gst_reserved;
+  } abidata;
 };
 
 struct _GstEventClass {
@@ -369,6 +372,10 @@ const GstStructure *
 
 gboolean        gst_event_has_name              (GstEvent *event, const gchar *name);
 
+/* identifiers for events and messages */
+guint32         gst_event_get_seqnum            (GstEvent *event);
+void            gst_event_set_seqnum            (GstEvent *event, guint32 seqnum);
+
 /* flush events */
 GstEvent *	gst_event_new_flush_start	(void);
 GstEvent *	gst_event_new_flush_stop	(void);

gst/gstmessage.c

@@ -60,6 +60,8 @@
 #include "gstquark.h"
 
 
+#define GST_MESSAGE_SEQNUM(e) ((GstMessage*)e)->abidata.ABI.seqnum
+
 static void gst_message_init (GTypeInstance * instance, gpointer g_class);
 static void gst_message_class_init (gpointer g_class, gpointer class_data);
 static void gst_message_finalize (GstMessage * message);
@@ -247,6 +249,7 @@ _gst_message_copy (GstMessage * message)
   GST_MESSAGE_COND (copy) = GST_MESSAGE_COND (message);
   GST_MESSAGE_TYPE (copy) = GST_MESSAGE_TYPE (message);
   GST_MESSAGE_TIMESTAMP (copy) = GST_MESSAGE_TIMESTAMP (message);
+  GST_MESSAGE_SEQNUM (copy) = GST_MESSAGE_SEQNUM (message);
 
   if (GST_MESSAGE_SRC (message)) {
     GST_MESSAGE_SRC (copy) = gst_object_ref (GST_MESSAGE_SRC (message));
@@ -300,9 +303,65 @@ gst_message_new_custom (GstMessageType type, GstObject * src,
   }
   message->structure = structure;
 
+  GST_MESSAGE_SEQNUM (message) = gst_util_seqnum_next ();
+
   return message;
 }
 
+/**
+ * gst_message_get_seqnum:
+ * @message: A #GstMessage.
+ *
+ * Retrieve the sequence number of a message.
+ *
+ * Messages have ever-incrementing sequence numbers, which may also be set
+ * explicitly via gst_message_set_seqnum(). Sequence numbers are typically used
+ * to indicate that a message corresponds to some other set of messages or
+ * events, for example a SEGMENT_DONE message corresponding to a SEEK event. It
+ * is considered good practice to make this correspondence when possible, though
+ * it is not required.
+ *
+ * Note that events and messages share the same sequence number incrementor;
+ * two events or messages will never not have the same sequence number unless
+ * that correspondence was made explicitly.
+ *
+ * Returns: The message's sequence number.
+ *
+ * Since: 0.10.22
+ *
+ * MT safe.
+ */
+guint32
+gst_message_get_seqnum (GstMessage * message)
+{
+  g_return_val_if_fail (GST_IS_MESSAGE (message), -1);
+
+  return GST_MESSAGE_SEQNUM (message);
+}
+
+/**
+ * gst_message_set_seqnum:
+ * @message: A #GstMessage.
+ * @seqnum: A sequence number.
+ *
+ * Set the sequence number of a message.
+ *
+ * This function might be called by the creator of a message to indicate that
+ * the message relates to other messages or events. See gst_message_get_seqnum()
+ * for more information.
+ *
+ * Since: 0.10.22
+ *
+ * MT safe.
+ */
+void
+gst_message_set_seqnum (GstMessage * message, guint32 seqnum)
+{
+  g_return_if_fail (GST_IS_MESSAGE (message));
+
+  GST_MESSAGE_SEQNUM (message) = seqnum;
+}
+
 /**
  * gst_message_new_eos:
  * @src: The object originating the message.

gst/gstmessage.h

@@ -219,7 +219,13 @@ struct _GstMessage
   GstStructure *structure;
 
   /*< private > */
-  gpointer _gst_reserved[GST_PADDING];
+  union {
+    struct {
+      guint32 seqnum;
+    } ABI;
+    /* + 0 to mark ABI change for future greppage */
+    gpointer _gst_reserved[GST_PADDING + 0];
+  } abidata;
 };
 
 struct _GstMessageClass {
@@ -284,6 +290,10 @@ gst_message_ref (GstMessage * msg)
  */
 #define         gst_message_make_writable(msg)	GST_MESSAGE (gst_mini_object_make_writable (GST_MINI_OBJECT (msg)))
 
+/* identifiers for events and messages */
+guint32         gst_message_get_seqnum          (GstMessage *message);
+void            gst_message_set_seqnum          (GstMessage *message, guint32 seqnum);
+
 /* EOS */
 GstMessage *	gst_message_new_eos		(GstObject * src);
 

gst/gstutils.c

@@ -575,6 +575,52 @@ overflow:
   }
 }
 
+/**
+ * gst_util_seqnum_next:
+ *
+ * Return a constantly incrementing sequence number.
+ *
+ * This function is used internally to GStreamer to be able to determine which
+ * events and messages are "the same". For example, elements may set the seqnum
+ * on a segment-done message to be the same as that of the last seek event, to
+ * indicate that event and the message correspond to the same segment.
+ *
+ * Returns: A constantly incrementing 32-bit unsigned integer, which might
+ * overflow back to 0 at some point. Use gst_util_seqnum_compare() to make sure
+ * you handle wraparound correctly.
+ *
+ * Since: 0.10.22
+ */
+guint32
+gst_util_seqnum_next (void)
+{
+  static gint counter = -1;
+  gint ret;
+
+  ret = g_atomic_int_exchange_and_add (&counter, 1);
+  return (guint32) (ret + 1);
+}
+
+/**
+ * gst_util_seqnum_compare:
+ * @s1: A sequence number.
+ * @s2: Another sequence number.
+ *
+ * Compare two sequence numbers, handling wraparound.
+ * 
+ * The current implementation just returns (gint32)(@s1 - @s2).
+ *
+ * Returns: A negative number if @s1 is before @s2, 0 if they are equal, or a
+ * positive number if @s1 is after @s2.
+ *
+ * Since: 0.10.22
+ */
+gint32
+gst_util_seqnum_compare (guint32 s1, guint32 s2)
+{
+  return (gint32) (s1 - s2);
+}
+
 /* -----------------------------------------------------
  *
  *  The following code will be moved out of the main

gst/gstutils.h

@@ -67,6 +67,9 @@ guint64		gst_util_uint64_scale		(guint64 val, guint64 num, guint64 denom);
 
 guint64         gst_util_uint64_scale_int       (guint64 val, gint num, gint denom);
 
+guint32         gst_util_seqnum_next            (void);
+gint32          gst_util_seqnum_compare         (guint32 s1, guint32 s2);
+
 void		gst_print_pad_caps		(GString *buf, gint indent, GstPad *pad);
 void		gst_print_element_args		(GString *buf, gint indent, GstElement *element);
 

win32/common/config.h

@@ -24,7 +24,7 @@
 /* #undef GST_GCOV_ENABLED */
 
 /* Default errorlevel to use */
-#define GST_LEVEL_DEFAULT GST_LEVEL_NONE
+#define GST_LEVEL_DEFAULT GST_LEVEL_ERROR
 
 /* GStreamer license */
 #define GST_LICENSE "LGPL"
@@ -33,7 +33,7 @@
 #define GST_MAJORMINOR "0.10"
 
 /* package name in plugins */
-#define GST_PACKAGE_NAME "GStreamer source release"
+#define GST_PACKAGE_NAME "GStreamer CVS/prerelease"
 
 /* package origin */
 #define GST_PACKAGE_ORIGIN "Unknown package origin"
@@ -197,13 +197,13 @@
 #define PACKAGE_NAME "GStreamer"
 
 /* Define to the full name and version of this package. */
-#define PACKAGE_STRING "GStreamer 0.10.21"
+#define PACKAGE_STRING "GStreamer 0.10.21.1"
 
 /* Define to the one symbol short name of this package. */
 #define PACKAGE_TARNAME "gstreamer"
 
 /* Define to the version of this package. */
-#define PACKAGE_VERSION "0.10.21"
+#define PACKAGE_VERSION "0.10.21.1"
 
 /* Define the plugin directory */
 #ifdef _DEBUG
@@ -219,7 +219,7 @@
 #undef USE_POISONING
 
 /* Version number of package */
-#define VERSION "0.10.21"
+#define VERSION "0.10.21.1"
 
 /* Define to 1 if your processor stores words with the most significant byte
    first (like Motorola and SPARC, unlike Intel and VAX). */