Event Tracing API wrapper (#1452)

* Add C# API wrappers for Span, Item, EventData data operations

* Add wrappers for Event Tracer logic

* Add Parameter Conversions

* Use closures to convert from external to internal Event

* Add Event Tracer parameter conversion closure

* Update Worker SDK IO bindings to support v14.8.0

* Add changelog entry

Author: Sean Parker

CHANGELOG.md

@@ -11,6 +11,7 @@
 ### Added
 
 - Added `MeansImplicitUse` attribute to `RequireAttribute` to reduce warnings in Rider IDE. [#1462](https://github.com/spatialos/gdk-for-unity/pull/1462)
+- Added Event Tracing API. [#1452](https://github.com/spatialos/gdk-for-unity/pull/1452)
 
 ### Changed
 

workers/unity/Packages/io.improbable.worker.sdk/CEventTrace.cs

@@ -18,13 +18,27 @@ internal unsafe class CEventTrace
          * Data for an event. This is a collection of key-value pairs (fields). Use EventData* functions to
          * read or write fields.
          */
-        public class EventData : CptrHandle
+        public class EventDataHandle : CptrHandle
         {
+            public EventDataHandle()
+            {
+            }
+
+            internal EventDataHandle(IntPtr handle)
+            {
+                SetHandle(handle);
+            }
+
             protected override bool ReleaseHandle()
             {
                 EventDataDestroy(handle);
                 return true;
             }
+
+            internal IntPtr GetUnderlying()
+            {
+                return handle;
+            }
         }
 
         public class EventTracer : CptrHandle
@@ -100,7 +114,7 @@ public struct Span
          */
         [DllImport(Constants.WorkerLibrary, CallingConvention = CallingConvention.Cdecl,
             EntryPoint = "Trace_EventData_Create")]
-        public static extern EventData EventDataCreate();
+        public static extern EventDataHandle EventDataCreate();
 
         /** Frees resources for the event data object.*/
         [DllImport(Constants.WorkerLibrary, CallingConvention = CallingConvention.Cdecl,
@@ -113,12 +127,12 @@ public struct Span
          */
         [DllImport(Constants.WorkerLibrary, CallingConvention = CallingConvention.Cdecl,
             EntryPoint = "Trace_EventData_AddStringFields")]
-        public static extern void EventDataAddStringFields(EventData data, Uint32 count, Char** keys, Char** values);
+        public static extern void EventDataAddStringFields(EventDataHandle data, Uint32 count, Char** keys, Char** values);
 
         /** Returns the number of fields on the given event data object. */
         [DllImport(Constants.WorkerLibrary, CallingConvention = CallingConvention.Cdecl,
             EntryPoint = "Trace_EventData_GetFieldCount")]
-        public static extern Uint32 EventDataGetFieldCount(EventData data);
+        public static extern Uint32 EventDataGetFieldCount(EventDataHandle data);
 
         /**
          * Returns all the key value pairs in the event data object. keys and values must have capacity for
@@ -128,12 +142,12 @@ public struct Span
          */
         [DllImport(Constants.WorkerLibrary, CallingConvention = CallingConvention.Cdecl,
             EntryPoint = "Trace_EventData_GetStringFields")]
-        public static extern void EventDataGetStringFields(EventData data, Char** keys, Char** values);
+        public static extern void EventDataGetStringFields(EventDataHandle data, Char** keys, Char** values);
 
         /** Returns the value for the given key. */
         [DllImport(Constants.WorkerLibrary, CallingConvention = CallingConvention.Cdecl,
             EntryPoint = "Trace_EventData_GetFieldValue")]
-        public static extern Char* EventDataGetFieldValue(EventData data, Char* key);
+        public static extern Char* EventDataGetFieldValue(EventDataHandle data, Char* key);
 
         /** Data for an event added to the event-tracer. */
         [StructLayout(LayoutKind.Sequential)]
@@ -153,7 +167,7 @@ public struct Event
         public struct Item
         {
             /** The type of the item, defined using ItemType. */
-            public Uint8 ItemType;
+            public ItemType ItemType;
 
             /** An item can either be a Span or an Event. */
             public Union ItemUnion;
@@ -187,12 +201,12 @@ public struct EventTracerParameters
 
         /** Creates an event-tracer. */
         [DllImport(Constants.WorkerLibrary, CallingConvention = CallingConvention.Cdecl,
-            EntryPoint = "EventTracerCreate")]
+            EntryPoint = "Trace_EventTracer_Create")]
         public static extern EventTracer EventTracerCreate(EventTracerParameters* parameters);
 
         /** Frees resources for an event-tracer. */
         [DllImport(Constants.WorkerLibrary, CallingConvention = CallingConvention.Cdecl,
-            EntryPoint = "EventTracerDestroy")]
+            EntryPoint = "Trace_EventTracer_Destroy")]
         public static extern void EventTracerDestroy(IntPtr eventTracer);
 
         /**
@@ -234,8 +248,8 @@ public struct EventTracerParameters
          * EventTracerGetActiveSpanId will return a null span ID.
          */
         [DllImport(Constants.WorkerLibrary, CallingConvention = CallingConvention.Cdecl,
-            EntryPoint = "Trace_EventTracer_UnsetActiveSpanId")]
-        public static extern void EventTracerUnsetActiveSpanId(EventTracer eventTracer);
+            EntryPoint = "Trace_EventTracer_ClearActiveSpanId")]
+        public static extern void EventTracerClearActiveSpanId(EventTracer eventTracer);
 
         /** Gets the active span ID on the event-tracer. */
         [DllImport(Constants.WorkerLibrary, CallingConvention = CallingConvention.Cdecl,
@@ -272,7 +286,7 @@ public struct EventTracerParameters
          * The item is initialized by copying the provided item; pass a NULL item argument to create an
          * item in an uninitialized state.
          *
-         * Directly creating a TraceItem object (on the stack or the heap) by other means than calling this
+         * Directly creating a Item object (on the stack or the heap) by other means than calling this
          * method is discouraged as it will lead to undefined behaviour when passing that item to certain
          * trace API methods (e.g. SerializeItemToStream).
          */

workers/unity/Packages/io.improbable.worker.sdk/CIO.cs

@@ -1,3 +1,4 @@
+using System;
 using System.Runtime.InteropServices;
 using Int64 = System.Int64;
 using Uint64 = System.UInt64;
@@ -28,10 +29,31 @@ protected override bool ReleaseHandle()
             }
         }
 
-        public enum OpenMode
+        [Flags]
+        public enum OpenModes : Uint32
         {
-            /* Opens the stream in the default mode. */
-            OpenModeDefault = 0x00,
+            /**
+             * Allow input operations on the stream. Input operations always occur at the read position, which
+             * is initialized to the beginning of the stream.
+             */
+            OpenModeRead = 0x01,
+
+            /**
+             * Allow output operations on the stream. Output operations always occur at the write position,
+             * which is initialized to the end of the stream.
+             */
+            OpenModeWrite = 0x02,
+
+            /**
+             * Truncates any existing content upon opening. If not set, writes are appended to the end of the
+             * stream's existing content.
+             */
+            OpenModeTruncate = 0x04,
+
+            /**
+             * Specify that writes should be appended to the stream's existing content, if any exists.
+             */
+            OpenModeAppend = 0x08,
         }
 
         /**
@@ -85,16 +107,14 @@ public enum OpenMode
          * The file stream has a conceptually infinite capacity; its true capacity depends on the
          * underlying filesystem.
          *
-         * Upon creation of the file stream, the file is created if it does not exist. The file stream is
-         * initialized to read from the beginning of the file and append to the end, regardless of whether
-         * it previously existed or not.
+         * The open_mode argument should be passed as a combination of OpenMode values.
          *
-         * Returns a pointer to a file stream. Never returns NULL. Call StreamGetLastError to check
-         * if an error occurred during file stream creation.
+         * Returns a pointer to a file stream. Never returns NULL. You *must* call Io_Stream_GetLastError to
+         * check if an error occurred during file stream creation.
          */
         [DllImport(Constants.WorkerLibrary, CallingConvention = CallingConvention.Cdecl,
             EntryPoint = "Io_CreateFileStream")]
-        public static extern StreamHandle CreateFileStream(Char* filename, OpenMode openMode);
+        public static extern StreamHandle CreateFileStream(Char* filename, OpenModes openModes);
 
         /* Destroys the I/O stream. */
         [DllImport(Constants.WorkerLibrary, CallingConvention = CallingConvention.Cdecl,
@@ -168,5 +188,13 @@ public enum OpenMode
         [DllImport(Constants.WorkerLibrary, CallingConvention = CallingConvention.Cdecl,
             EntryPoint = "Io_Stream_GetLastError")]
         public static extern Char* StreamGetLastError(StreamHandle stream);
+
+        /**
+         * Clears the stream's current error such that the next call to Io_Stream_GetLastError returns
+         * nullptr.
+         */
+        [DllImport(Constants.WorkerLibrary, CallingConvention = CallingConvention.Cdecl,
+            EntryPoint = "Io_Stream_ClearError")]
+        public static extern void StreamClearError(StreamHandle stream);
     }
 }