dm vdo wait-queue: add proper namespace to interface

Rename various interfaces and structs associated with vdo's wait-queue,
e.g.: s/wait_queue/vdo_wait_queue/, s/waiter/vdo_waiter/, etc.

Now all function names start with "vdo_waitq_" or "vdo_waiter_".

Reviewed-by: Ken Raeburn <raeburn@redhat.com>
Signed-off-by: Mike Snitzer <snitzer@kernel.org>
Signed-off-by: Matthew Sakai <msakai@redhat.com>

1 files changed, 70 insertions, 60 deletions

diff --git a/drivers/md/dm-vdo/wait-queue.h b/drivers/md/dm-vdo/wait-queue.h
index 50f1e2a1ea67..b92f12dd5b4b 100644
--- a/drivers/md/dm-vdo/wait-queue.h
+++ b/drivers/md/dm-vdo/wait-queue.h
@@ -10,122 +10,132 @@
 #include <linux/types.h>
 
 /**
- * DOC: Wait queues.
+ * A vdo_wait_queue is a circular singly linked list of entries waiting to be notified
+ * of a change in a condition. Keeping a circular list allows the vdo_wait_queue
+ * structure to simply be a pointer to the tail (newest) entry, supporting
+ * constant-time enqueue and dequeue operations. A null pointer is an empty waitq.
  *
- * A wait queue is a circular list of entries waiting to be notified of a change in a condition.
- * Keeping a circular list allows the queue structure to simply be a pointer to the tail (newest)
- * entry in the queue, supporting constant-time enqueue and dequeue operations. A null pointer is
- * an empty queue.
+ *   An empty waitq:
+ *     waitq0.last_waiter -> NULL
  *
- *   An empty queue:
- *     queue0.last_waiter -> NULL
+ *   A singleton waitq:
+ *     waitq1.last_waiter -> entry1 -> entry1 -> [...]
  *
- *   A singleton queue:
- *     queue1.last_waiter -> entry1 -> entry1 -> [...]
+ *   A three-element waitq:
+ *     waitq2.last_waiter -> entry3 -> entry1 -> entry2 -> entry3 -> [...]
  *
- *   A three-element queue:
- *     queue2.last_waiter -> entry3 -> entry1 -> entry2 -> entry3 -> [...]
+ *   linux/wait.h's wait_queue_head is _not_ used because vdo_wait_queue's
+ *   interface is much less complex (doesn't need locking, priorities or timers).
+ *   Made possible by vdo's thread-based resource allocation and locking; and
+ *   the polling nature of vdo_wait_queue consumers.
+ *
+ *   FIXME: could be made to use a linux/list.h's list_head but its extra barriers
+ *   really aren't needed. Nor is a doubly linked list, but vdo_wait_queue could
+ *   make use of __list_del_clearprev() -- but that would compromise the ability
+ *   to make full use of linux's list interface.
  */
 
-struct waiter;
+struct vdo_waiter;
 
-struct wait_queue {
+struct vdo_wait_queue {
 	/* The tail of the queue, the last (most recently added) entry */
-	struct waiter *last_waiter;
+	struct vdo_waiter *last_waiter;
 	/* The number of waiters currently in the queue */
-	size_t queue_length;
+	size_t length;
 };
 
 /**
- * typedef waiter_callback_fn - Callback type for functions which will be called to resume
- *                              processing of a waiter after it has been removed from its wait
- *                              queue.
+ * vdo_waiter_callback_fn - Callback type that will be called to resume processing
+ *                          of a waiter after it has been removed from its wait queue.
  */
-typedef void (*waiter_callback_fn)(struct waiter *waiter, void *context);
+typedef void (*vdo_waiter_callback_fn)(struct vdo_waiter *waiter, void *context);
 
 /**
- * typedef waiter_match_fn - Method type for waiter matching methods.
+ * vdo_waiter_match_fn - Method type for waiter matching methods.
  *
- * A waiter_match_fn method returns false if the waiter does not match.
+ * Returns false if the waiter does not match.
  */
-typedef bool (*waiter_match_fn)(struct waiter *waiter, void *context);
+typedef bool (*vdo_waiter_match_fn)(struct vdo_waiter *waiter, void *context);
 
-/* The queue entry structure for entries in a wait_queue. */
-struct waiter {
+/* The structure for entries in a vdo_wait_queue. */
+struct vdo_waiter {
 	/*
-	 * The next waiter in the queue. If this entry is the last waiter, then this is actually a
-	 * pointer back to the head of the queue.
+	 * The next waiter in the waitq. If this entry is the last waiter, then this
+	 * is actually a pointer back to the head of the waitq.
 	 */
-	struct waiter *next_waiter;
+	struct vdo_waiter *next_waiter;
 
-	/* Optional waiter-specific callback to invoke when waking this waiter. */
-	waiter_callback_fn callback;
+	/* Optional waiter-specific callback to invoke when dequeuing this waiter. */
+	vdo_waiter_callback_fn callback;
 };
 
 /**
- * is_waiting() - Check whether a waiter is waiting.
+ * vdo_waiter_is_waiting() - Check whether a waiter is waiting.
  * @waiter: The waiter to check.
  *
- * Return: true if the waiter is on some wait_queue.
+ * Return: true if the waiter is on some vdo_wait_queue.
  */
-static inline bool vdo_is_waiting(struct waiter *waiter)
+static inline bool vdo_waiter_is_waiting(struct vdo_waiter *waiter)
 {
 	return (waiter->next_waiter != NULL);
 }
 
 /**
- * initialize_wait_queue() - Initialize a wait queue.
- * @queue: The queue to initialize.
+ * vdo_waitq_init() - Initialize a vdo_wait_queue.
+ * @waitq: The vdo_wait_queue to initialize.
  */
-static inline void vdo_initialize_wait_queue(struct wait_queue *queue)
+static inline void vdo_waitq_init(struct vdo_wait_queue *waitq)
 {
-	*queue = (struct wait_queue) {
+	*waitq = (struct vdo_wait_queue) {
 		.last_waiter = NULL,
-		.queue_length = 0,
+		.length = 0,
 	};
 }
 
 /**
- * has_waiters() - Check whether a wait queue has any entries waiting in it.
- * @queue: The queue to query.
+ * vdo_waitq_has_waiters() - Check whether a vdo_wait_queue has any entries waiting.
+ * @waitq: The vdo_wait_queue to query.
  *
- * Return: true if there are any waiters in the queue.
+ * Return: true if there are any waiters in the waitq.
  */
-static inline bool __must_check vdo_has_waiters(const struct wait_queue *queue)
+static inline bool __must_check vdo_waitq_has_waiters(const struct vdo_wait_queue *waitq)
 {
-	return (queue->last_waiter != NULL);
+	return (waitq->last_waiter != NULL);
 }
 
-void vdo_enqueue_waiter(struct wait_queue *queue, struct waiter *waiter);
+void vdo_waitq_enqueue_waiter(struct vdo_wait_queue *waitq,
+			      struct vdo_waiter *waiter);
 
-void vdo_notify_all_waiters(struct wait_queue *queue, waiter_callback_fn callback,
-			    void *context);
+void vdo_waitq_notify_all_waiters(struct vdo_wait_queue *waitq,
+				  vdo_waiter_callback_fn callback, void *context);
 
-bool vdo_notify_next_waiter(struct wait_queue *queue, waiter_callback_fn callback,
-			    void *context);
+bool vdo_waitq_notify_next_waiter(struct vdo_wait_queue *waitq,
+				  vdo_waiter_callback_fn callback, void *context);
 
-void vdo_transfer_all_waiters(struct wait_queue *from_queue,
-			      struct wait_queue *to_queue);
+void vdo_waitq_transfer_all_waiters(struct vdo_wait_queue *from_waitq,
+				    struct vdo_wait_queue *to_waitq);
 
-struct waiter *vdo_get_first_waiter(const struct wait_queue *queue);
+struct vdo_waiter *vdo_waitq_get_first_waiter(const struct vdo_wait_queue *waitq);
 
-void vdo_dequeue_matching_waiters(struct wait_queue *queue, waiter_match_fn match_method,
-				  void *match_context, struct wait_queue *matched_queue);
+void vdo_waitq_dequeue_matching_waiters(struct vdo_wait_queue *waitq,
+					vdo_waiter_match_fn waiter_match,
+					void *match_context,
+					struct vdo_wait_queue *matched_waitq);
 
-struct waiter *vdo_dequeue_next_waiter(struct wait_queue *queue);
+struct vdo_waiter *vdo_waitq_dequeue_next_waiter(struct vdo_wait_queue *waitq);
 
 /**
- * count_waiters() - Count the number of waiters in a wait queue.
- * @queue: The wait queue to query.
+ * vdo_waitq_num_waiters() - Return the number of waiters in a vdo_wait_queue.
+ * @waitq: The vdo_wait_queue to query.
  *
- * Return: The number of waiters in the queue.
+ * Return: The number of waiters in the waitq.
  */
-static inline size_t __must_check vdo_count_waiters(const struct wait_queue *queue)
+static inline size_t __must_check vdo_waitq_num_waiters(const struct vdo_wait_queue *waitq)
 {
-	return queue->queue_length;
+	return waitq->length;
 }
 
-const struct waiter * __must_check vdo_get_next_waiter(const struct wait_queue *queue,
-						       const struct waiter *waiter);
+const struct vdo_waiter * __must_check
+vdo_waitq_get_next_waiter(const struct vdo_wait_queue *waitq, const struct vdo_waiter *waiter);
 
 #endif /* VDO_WAIT_QUEUE_H */