Document ::OnColumnChange semantics a little bit more clearly

frioux · Apr 6, 2015 · b20cb17 · b20cb17
1 parent d905315
commit b20cb17
Show file tree

Hide file tree

Showing 2 changed files with 10 additions and 0 deletions.
diff --git a/Changes b/Changes
@@ -3,6 +3,7 @@ Revision history for {{$dist->name}}
 {{$NEXT}}
  - Make ::OnColumnChange always allow mutating values before update
  - Fix documented args for `after_column_change`
+ - Document ::OnColumnChange semantics a little bit more clearly
 
 2.025002  2015-03-21 00:03:43-05:00 America/Chicago
  - Migrate ::RS::CorelateRelationship to an importable Util

diff --git a/lib/DBIx/Class/Helper/Row/OnColumnChange.pm b/lib/DBIx/Class/Helper/Row/OnColumnChange.pm
@@ -334,3 +334,12 @@ If used in conjunction with L<DBIx::Class::Candy> this component will export:
 =item after_column_change
 
 =back
+
+=head1 NO SURPRISE RACE CONDITIONS
+
+One thing that should be made totally clear is that the column change callbacks
+are in effect B<< only once >> in a given update.  If you expect to be able to
+do something weird like calling one of the callbacks which changes a value with
+an accessor which calls a callback etc etc, you probably just need to write some
+code to do that yourself.  This helper is specifically made with the aim of
+reacting to changes immediately before they hit the database.