list.h: add list_singleton

Add list_singleton to check a list has just one entry.

list_singleton is useful to check whether a list_head which have been temporarily allocated for listing objects can be released or not.

Signed-off-by Masami Hiramatsu <[email protected]>

---
 include/linux/list.h |    9 +++++++++
 1 file changed, 9 insertions(+)

Index: 2.6.25-rc5-mm1/include/linux/list.h
===================================================================

include/linux/list.h +0 -0

@@ -211,6 +211,15 @@ static inline int list_empty_careful(con
 	return (next == head) && (next == head->prev);
 }

If your usage pattern is:

struct foo {
	...
	struct list_head bar_list;	/* A list of `struct bar's */
};

struct bar {
	struct list_head list;		/* Attached to foo.bar_list */
	...
};

then yes, list_singleton() makes sense.

But in other usage patterns it does not:

struct foo {
	struct bar *bar_list;
	...
};

struct bar {
	struct list_head list;		/* All the other bars go here */
	...
};

In the second case, emptiness is signified by foo.bar_list==NULL. And in this case, code which does

	if (foo->bar_list && list_singleton(&foo->bar_list->list))

will fail if there is a single item on the list!

The second usage pattern is uncommon and list_empty() also returns misleading answers when list_heads are used this way.

So I guess we can proceed with your list_singleton(), but I'd just like to flag this possible confusion, see what people think..

Quoted 29 lines · Andrew Morton

If your usage pattern is:

struct foo {
	...
	struct list_head bar_list;	/* A list of `struct bar's */
};

struct bar {
	struct list_head list;		/* Attached to foo.bar_list */
	...
};

then yes, list_singleton() makes sense.

But in other usage patterns it does not:

struct foo {
	struct bar *bar_list;
	...
};

struct bar {
	struct list_head list;		/* All the other bars go here */
	...
};

In the second case, emptiness is signified by foo.bar_list==NULL. And in this case, code which does

Quoted 6 lines

	if (foo->bar_list && list_singleton(&foo->bar_list->list))

will fail if there is a single item on the list!

The second usage pattern is uncommon and list_empty() also returns misleading answers when list_heads are used this way.

I agreed. I assume that list_singleton() is used like as list_empty().

Quoted 2 lines

So I guess we can proceed with your list_singleton(), but I'd just like to flag this possible confusion, see what people think..

Quoted 2 lines

Quoted 2 lines

So I guess we can proceed with your list_singleton(), but I'd just like to flag this possible confusion, see what people think..

May I kindly ask to please not use the singleton name like this. It does not implement the singleton pattern and will be a great confusion for everybody who expects it to.

Hi Peter,

Quoted 6 lines · Peter Zijlstra

Quoted 2 lines

Quoted 2 lines

So I guess we can proceed with your list_singleton(), but I'd just like to flag this possible confusion, see what people think..

May I kindly ask to please not use the singleton name like this. It does not implement the singleton pattern and will be a great confusion for everybody who expects it to.

Indeed.

I have some other candidates.
- list_single
- list_has_one
- list_one

Could you tell me which or some other name you recommend?

I think list_has_one() or list_is_singular() are good names, they convey they are a test for a condition by using a form of be.