From c62bab2173447867f3230f949d816e4acac47f1b Mon Sep 17 00:00:00 2001 From: rillig Date: Wed, 2 Sep 2020 23:33:13 +0000 Subject: [PATCH] make(1): improve grouping of the Lst functions Lst_IsEmpty does not belong in the "create and destroy" group, but in "query information without modifying anything". The functions named LstNode_* all belong together. They do not provide much abstraction, but still they restrict the API and hide a few struct fields that are only used internally by Lst_Open/Lst_Close and Lst_ForEach. Use consistent wording in the documentation of the functions (list, node, datum). --- usr.bin/make/lst.h | 174 +++++++++++++++++++++++---------------------- 1 file changed, 88 insertions(+), 86 deletions(-) diff --git a/usr.bin/make/lst.h b/usr.bin/make/lst.h index 32aea63fa522..d9aa9feb3b65 100644 --- a/usr.bin/make/lst.h +++ b/usr.bin/make/lst.h @@ -1,4 +1,4 @@ -/* $NetBSD: lst.h,v 1.59 2020/08/30 11:15:05 rillig Exp $ */ +/* $NetBSD: lst.h,v 1.60 2020/09/02 23:33:13 rillig Exp $ */ /* * Copyright (c) 1988, 1989, 1990 The Regents of the University of California. @@ -73,105 +73,107 @@ * from: @(#)lst.h 8.1 (Berkeley) 6/6/93 */ -/*- - * lst.h -- - * Header for using the list library - */ +/* Doubly-linked lists of arbitrary pointers. */ + #ifndef MAKE_LST_H #define MAKE_LST_H -#include -#include - -/* - * basic typedef. This is what the Lst_ functions handle - */ +#include +#include +/* A doubly-linked list of pointers. */ typedef struct List *Lst; +/* A single node in the doubly-linked list. */ typedef struct ListNode *LstNode; +/* Copy a node, usually by allocating a copy of the given object. + * For reference-counted objects, the original object may need to be + * modified, therefore the parameter is not const. */ typedef void *LstCopyProc(void *); +/* Free the datum of a node, called before freeing the node itself. */ typedef void LstFreeProc(void *); -typedef Boolean LstFindProc(const void *, const void *); -typedef int LstActionProc(void *, void *); +/* Return TRUE if the datum matches the args, for Lst_Find. */ +typedef Boolean LstFindProc(const void *datum, const void *args); +/* An action for Lst_ForEach. */ +typedef int LstActionProc(void *datum, void *args); -/* - * Creation/destruction functions - */ -/* Create a new list */ -Lst Lst_Init(void); -/* Duplicate an existing list */ -Lst Lst_Copy(Lst, LstCopyProc); -/* Destroy an old one */ -void Lst_Free(Lst); -void Lst_Destroy(Lst, LstFreeProc); -/* True if list is empty */ -Boolean Lst_IsEmpty(Lst); +/* Create or destroy a list */ -/* - * Functions to modify a list - */ -/* Insert an element before another */ -void Lst_InsertBefore(Lst, LstNode, void *); -/* Place an element at the front of a lst. */ -void Lst_Prepend(Lst, void *); -/* Place an element at the end of a lst. */ -void Lst_Append(Lst, void *); -/* Remove an element */ -void Lst_Remove(Lst, LstNode); -/* Replace a node with a new value */ -void LstNode_Set(LstNode, void *); -void LstNode_SetNull(LstNode); +/* Create a new list. */ +Lst Lst_Init(void); +/* Duplicate an existing list. */ +Lst Lst_Copy(Lst, LstCopyProc); +/* Free the list, leaving the node data unmodified. */ +void Lst_Free(Lst); +/* Free the list, freeing the node data using the given function. */ +void Lst_Destroy(Lst, LstFreeProc); -void Lst_PrependAll(Lst, Lst); -void Lst_AppendAll(Lst, Lst); -void Lst_MoveAll(Lst, Lst); +/* Get information about a list */ -/* - * Node-specific functions - */ -/* Return first element in list */ -LstNode Lst_First(Lst); -/* Return last element in list */ -LstNode Lst_Last(Lst); -/* Return successor to given element */ -LstNode LstNode_Next(LstNode); -/* Return predecessor to given element */ -LstNode LstNode_Prev(LstNode); -/* Get datum from LstNode */ -void *LstNode_Datum(LstNode); +Boolean Lst_IsEmpty(Lst); +/* Return the first node of the list, or NULL. */ +LstNode Lst_First(Lst); +/* Return the last node of the list, or NULL. */ +LstNode Lst_Last(Lst); +/* Find the first node for which the function returns TRUE, or NULL. */ +LstNode Lst_Find(Lst, LstFindProc, const void *); +/* Find the first node for which the function returns TRUE, or NULL. + * The search starts at the given node, towards the end of the list. */ +LstNode Lst_FindFrom(Lst, LstNode, LstFindProc, const void *); +/* Find the first node that contains the given datum, or NULL. */ +LstNode Lst_FindDatum(Lst, const void *); -/* - * Functions for entire lists - */ -/* Find an element in a list */ -LstNode Lst_Find(Lst, LstFindProc, const void *); -/* Find an element starting from somewhere */ -LstNode Lst_FindFrom(Lst, LstNode, LstFindProc, const void *); -/* Return the first node that contains the given datum, or NULL. */ -LstNode Lst_FindDatum(Lst, const void *); -/* Apply a function to all elements of a lst */ -int Lst_ForEach(Lst, LstActionProc, void *); -/* Apply a function to all elements of a lst starting from a certain point. */ -int Lst_ForEachFrom(Lst, LstNode, LstActionProc, void *); -/* - * these functions are for dealing with a list as a table, of sorts. - * An idea of the "current element" is kept and used by all the functions - * between Lst_Open() and Lst_Close(). - */ -/* Open the list */ -void Lst_Open(Lst); -/* Next element please, or NULL */ -LstNode Lst_Next(Lst); -/* Finish table access */ -void Lst_Close(Lst); +/* Modify a list */ -/* - * for using the list as a queue - */ -/* Place an element at tail of queue */ -void Lst_Enqueue(Lst, void *); -/* Remove an element from head of queue */ -void *Lst_Dequeue(Lst); +/* Insert a datum before the given node. */ +void Lst_InsertBefore(Lst, LstNode, void *); +/* Place a datum at the front of the list. */ +void Lst_Prepend(Lst, void *); +/* Place a datum at the end of the list. */ +void Lst_Append(Lst, void *); +/* Remove the node from the list. */ +void Lst_Remove(Lst, LstNode); +void Lst_PrependAll(Lst, Lst); +void Lst_AppendAll(Lst, Lst); +void Lst_MoveAll(Lst, Lst); + +/* Node-specific functions */ + +/* Return the successor of the node, or NULL. */ +LstNode LstNode_Next(LstNode); +/* Return the predecessor of the node, or NULL. */ +LstNode LstNode_Prev(LstNode); +/* Return the datum of the node. Usually not NULL. */ +void *LstNode_Datum(LstNode); +/* Replace the value of the node. */ +void LstNode_Set(LstNode, void *); +/* Set the value of the node to NULL. Having NULL in a list is unusual. */ +void LstNode_SetNull(LstNode); + +/* Iterating over a list, using a callback function */ + +/* Apply a function to each datum of the list, until the callback function + * returns non-zero. */ +int Lst_ForEach(Lst, LstActionProc, void *); +/* Apply a function to each datum of the list, starting at the node, + * until the callback function returns non-zero. */ +int Lst_ForEachFrom(Lst, LstNode, LstActionProc, void *); + +/* Iterating over a list while keeping track of the current node and possible + * concurrent modifications */ + +/* Start iterating the list. */ +void Lst_Open(Lst); +/* Return the next node, or NULL. */ +LstNode Lst_Next(Lst); +/* Finish iterating the list. */ +void Lst_Close(Lst); + +/* Using the list as a queue */ + +/* Add a datum at the tail of the queue. */ +void Lst_Enqueue(Lst, void *); +/* Remove the head node of the queue and return its datum. */ +void *Lst_Dequeue(Lst); #endif /* MAKE_LST_H */