1 files changed, 34 insertions, 31 deletions

diff --git a/src/contrib/libngtcp2/ngtcp2/lib/ngtcp2_pq.h b/src/contrib/libngtcp2/ngtcp2/lib/ngtcp2_pq.h
index 484c8f2..2fe5e74 100644
--- a/src/contrib/libngtcp2/ngtcp2/lib/ngtcp2_pq.h
+++ b/src/contrib/libngtcp2/ngtcp2/lib/ngtcp2_pq.h
@@ -45,37 +45,39 @@ typedef struct ngtcp2_pq_entry {
   size_t index;
 } ngtcp2_pq_entry;
 
-/* "less" function, return nonzero if |lhs| is less than |rhs|. */
-typedef int (*ngtcp2_less)(const ngtcp2_pq_entry *lhs,
-                           const ngtcp2_pq_entry *rhs);
+/* ngtcp2_pq_less is a "less" function, that returns nonzero if |lhs|
+   is considered to be less than |rhs|. */
+typedef int (*ngtcp2_pq_less)(const ngtcp2_pq_entry *lhs,
+                              const ngtcp2_pq_entry *rhs);
 
 typedef struct ngtcp2_pq {
-  /* The pointer to the pointer to the item stored */
+  /* q is a pointer to an array that stores the items. */
   ngtcp2_pq_entry **q;
-  /* Memory allocator */
+  /* mem is a memory allocator. */
   const ngtcp2_mem *mem;
-  /* The number of items stored */
+  /* length is the number of items stored. */
   size_t length;
-  /* The maximum number of items this pq can store. This is
-     automatically extended when length is reached to this value. */
+  /* capacity is the maximum number of items this queue can store.
+     This is automatically extended when length is reached to this
+     limit. */
   size_t capacity;
-  /* The less function between items */
-  ngtcp2_less less;
+  /* less is the less function to compare items. */
+  ngtcp2_pq_less less;
 } ngtcp2_pq;
 
 /*
- * Initializes priority queue |pq| with compare function |cmp|.
+ * ngtcp2_pq_init initializes |pq| with compare function |cmp|.
  */
-void ngtcp2_pq_init(ngtcp2_pq *pq, ngtcp2_less less, const ngtcp2_mem *mem);
+void ngtcp2_pq_init(ngtcp2_pq *pq, ngtcp2_pq_less less, const ngtcp2_mem *mem);
 
 /*
- * Deallocates any resources allocated for |pq|.  The stored items are
- * not freed by this function.
+ * ngtcp2_pq_free deallocates any resources allocated for |pq|.  The
+ * stored items are not freed by this function.
  */
 void ngtcp2_pq_free(ngtcp2_pq *pq);
 
 /*
- * Adds |item| to the priority queue |pq|.
+ * ngtcp2_pq_push adds |item| to |pq|.
  *
  * This function returns 0 if it succeeds, or one of the following
  * negative error codes:
@@ -86,40 +88,41 @@ void ngtcp2_pq_free(ngtcp2_pq *pq);
 int ngtcp2_pq_push(ngtcp2_pq *pq, ngtcp2_pq_entry *item);
 
 /*
- * Returns item at the top of the queue |pq|.  It is undefined if the
- * queue is empty.
+ * ngtcp2_pq_top returns item at the top of |pq|.  It is undefined if
+ * |pq| is empty.
  */
-ngtcp2_pq_entry *ngtcp2_pq_top(ngtcp2_pq *pq);
+ngtcp2_pq_entry *ngtcp2_pq_top(const ngtcp2_pq *pq);
 
 /*
- * Pops item at the top of the queue |pq|. The popped item is not
- * freed by this function.
+ * ngtcp2_pq_pop pops item at the top of |pq|.  The popped item is not
+ * freed by this function.  It is undefined if |pq| is empty.
  */
 void ngtcp2_pq_pop(ngtcp2_pq *pq);
 
 /*
- * Returns nonzero if the queue |pq| is empty.
+ * ngtcp2_pq_empty returns nonzero if |pq| is empty.
  */
-int ngtcp2_pq_empty(ngtcp2_pq *pq);
+int ngtcp2_pq_empty(const ngtcp2_pq *pq);
 
 /*
- * Returns the number of items in the queue |pq|.
+ * ngtcp2_pq_size returns the number of items |pq| contains.
  */
-size_t ngtcp2_pq_size(ngtcp2_pq *pq);
+size_t ngtcp2_pq_size(const ngtcp2_pq *pq);
 
 typedef int (*ngtcp2_pq_item_cb)(ngtcp2_pq_entry *item, void *arg);
 
 /*
- * Applies |fun| to each item in |pq|.  The |arg| is passed as arg
- * parameter to callback function.  This function must not change the
- * ordering key.  If the return value from callback is nonzero, this
- * function returns 1 immediately without iterating remaining items.
- * Otherwise this function returns 0.
+ * ngtcp2_pq_each applies |fun| to each item in |pq|.  The |arg| is
+ * passed as arg parameter to callback function.  This function must
+ * not change the ordering key.  If the return value from callback is
+ * nonzero, this function returns 1 immediately without iterating
+ * remaining items.  Otherwise this function returns 0.
  */
-int ngtcp2_pq_each(ngtcp2_pq *pq, ngtcp2_pq_item_cb fun, void *arg);
+int ngtcp2_pq_each(const ngtcp2_pq *pq, ngtcp2_pq_item_cb fun, void *arg);
 
 /*
- * Removes |item| from priority queue.
+ * ngtcp2_pq_remove removes |item| from |pq|.  |pq| must contain
+ * |item| otherwise the behavior is undefined.
  */
 void ngtcp2_pq_remove(ngtcp2_pq *pq, ngtcp2_pq_entry *item);