svn commit: r280872 - in head/sys: kern sys

[Randall Stewart]

Author: rrs
Date: Tue Mar 31 00:18:00 2015
New Revision: 280872
URL: https://svnweb.freebsd.org/changeset/base/280872

Log:
  Adopt jhb's suggested changes, updated comments and callout_migration() moving
  to kern/kern_timeout.c
  
  This does *not* address his -1 -> NOCPU comment.
  
  Sponsored by:	Netflix Inc.

Modified:
  head/sys/kern/kern_timeout.c
  head/sys/sys/callout.h

Modified: head/sys/kern/kern_timeout.c
==============================================================================
--- head/sys/kern/kern_timeout.c	Tue Mar 31 00:15:27 2015	(r280871)
+++ head/sys/kern/kern_timeout.c	Tue Mar 31 00:18:00 2015	(r280872)
@@ -167,6 +167,8 @@ struct callout_cpu {
 	char			cc_ktr_event_name[20];
 };
 
+#define	callout_migrating(c)	((c)->c_iflags & CALLOUT_DFRMIGRATION)
+
 #define	cc_exec_curr(cc, dir)		cc->cc_exec_entity[dir].cc_curr
 #define	cc_exec_next(cc)		cc->cc_next
 #define	cc_exec_cancel(cc, dir)		cc->cc_exec_entity[dir].cc_cancel

Modified: head/sys/sys/callout.h
==============================================================================
--- head/sys/sys/callout.h	Tue Mar 31 00:15:27 2015	(r280871)
+++ head/sys/sys/callout.h	Tue Mar 31 00:18:00 2015	(r280872)
@@ -68,18 +68,18 @@ struct callout_handle {
  * field is the one that caller operations that may, or may not have
  * a lock touches i.e. callout_deactivate(). The other, the c_iflags,
  * is the internal flags that *must* be kept correct on which the
- * callout system depend on i.e. callout_migrating() & callout_pending(),
- * these are used internally by the callout system to determine which
- * list and other critical internal state. Callers *should not* use the 
- * c_flags field directly but should use the macros!
+ * callout system depend on e.g. callout_pending().
+ * The c_iflag is used internally by the callout system to determine which
+ * list the callout is on and track internal state. Callers *should not* 
+ * use the c_flags field directly but should use the macros provided.
  *  
- * If the caller wants to keep the c_flags field sane they 
- * should init with a mutex *or* if using the older
- * mpsafe option, they *must* lock there own lock
- * before calling callout_deactivate().
+ * The c_iflags field holds internal flags that are protected by internal
+ * locks of the callout subsystem.  The c_flags field holds external flags.
+ * The caller must hold its own lock while manipulating or reading external
+ * flags via callout_active(), callout_deactivate(), callout_reset*(), or
+ * callout_stop() to avoid races.
  */
 #define	callout_active(c)	((c)->c_flags & CALLOUT_ACTIVE)
-#define	callout_migrating(c)	((c)->c_iflags & CALLOUT_DFRMIGRATION)
 #define	callout_deactivate(c)	((c)->c_flags &= ~CALLOUT_ACTIVE)
 #define	callout_drain(c)	_callout_stop_safe(c, 1)
 void	callout_init(struct callout *, int);