Re: [PATCH] docbook: some kernel-locking fixes

From: Rusty Russell
Date: Thu Apr 03 2008 - 19:39:40 EST


On Thursday 03 April 2008 07:47:50 Randy Dunlap wrote:
> From: Matti Linnanvuori <mattilinnanvuori@xxxxxxxxx>
> +<chapter id="try-variants">
> + <title>The try variants</title>
> +
> + <para>
> + <function>spin_trylock()</function> does not spin but returns non-zero
> + if it acquires the spinlock on the first try or 0 if not.
> + </para>
> +
> + <para>
> + <function>mutex_trylock()</function> does not suspend your task
> + but returns non-zero if it could lock the mutex on the first try
> + or 0 if not.
> + </para>
> +
> + <para>
> + <function>down_trylock()</function> does not suspend your task
> + but returns 0 if it could get the semaphore on the first try or
> + non-zero if not. The return value is the inverse of that of
> + <function>spin_trylock()</function> and <function>mutex_trylock()
> + </function>.
> + </para>
> +</chapter>

OK, other than documenting the inconsistent horror of down_trylock, I don't
like this patch. This document is not about documenting the functions, but
providing an overview and pointing to them (where you can read to your
heart's content).

This is a worthy addition, but it's a paragraph, not a chapter. Unless you
want to document why you would use the trylock variants (can mutex_trylock
and down_trylock be used from interrupt context? Or are they only useful to
avoid deadlock? How are they actually used in the kernel?)

Thanks,
Rusty.
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/