UHPA comments.

src/mosquitto_broker.h

@@ -48,6 +48,47 @@ Contributors:
 /* ========================================
  * UHPA data types
  * ======================================== */
+
+/* See uhpa.h
+ *
+ * The idea here is that there is potentially a lot of wasted space (and time)
+ * in malloc calls for frequent, small heap allocations. This can happen if
+ * small payloads are used by clients or if individual topic elements are
+ * small.
+ *
+ * In both cases, a struct is used that includes a void* or char* pointer to
+ * point to the dynamically allocated memory used. To allocate and store a
+ * single byte needs the size of the pointer (8 bytes on a 64 bit
+ * architecture), the malloc overhead and the memory allocated itself (which
+ * will often be larger than the memory requested, on 64 bit Linux this can be
+ * a minimum of 24 bytes). To allocate and store 1 byte of heap memory we need
+ * in this example 32 bytes.
+ *
+ * UHPA uses a union to either store data in an array, or to allocate memory on
+ * the heap, depending on the size of the data being stored (this does mean
+ * that the size of the data must always be known). Setting the size of the
+ * array changes the point at which heap allocation starts. Using the example
+ * above, this means that an array size of 32 bytes should not result in any
+ * wasted space, and should be quicker as well. Certainly in the case of topic
+ * elements (e.g. "bar" out of "foo/bar/baz") it is likely that an array size
+ * of 32 bytes will mean that the majority of heap allocations are removed.
+ *
+ * You can change the size of MOSQ_PAYLOAD_UNION_SIZE and MOSQ_TOPIC_UNION_SIZE
+ * to change the size of the uhpa array used for the payload (i.e. the
+ * published part of a message) and for topic elements, and so control the heap
+ * allocation threshold for these data types. You should look at your
+ * application to decide what values to set, but don't set them too high
+ * otherwise your overall memory usage will increase.
+ *
+ * You could use something like heaptrack
+ * http://milianw.de/blog/heaptrack-a-heap-memory-profiler-for-linux to
+ * profile heap allocations.
+ *
+ * I would suggest that values for MOSQ_PAYLOAD_UNION_SIZE and
+ * MOSQ_TOPIC_UNION_SIZE that are equivalent to
+ * sizeof(void*)+malloc_usable_size(malloc(1)) are a safe value that should
+ * reduce calls to malloc without increasing memory usage at all.
+ */
 #define MOSQ_PAYLOAD_UNION_SIZE 8
 typedef union {
 	void *ptr;