Discuss the advisory lock in the README

README.md

@@ -225,6 +225,14 @@ item.update list: other_list, position: {after: 11}
 
 It's important to note that in the examples above, `other_item` must already belong to the `other_list` scope.
 
+## Concurrency
+
+The queries that this gem runs, especially those that seek the next position integer available are vulnerable to race conditions. To this end, we've introduced an Advisory Lock to ensure that our model callbacks that determine and assign positions run sequentially. In short, an advisory lock prevents more than one process from running a particular block of code at the same time. The lock occurs in the database (or in the case of SQLite, on the filesystem), so as long as all of your processes are using the same database, the lock will prevent multiple positioning callbacks from executing on the same table and positioning column combination at the same time. You're encouraged to review the Advisory Lock code to ensure it fits with your environment:
+
+https://github.com/brendon/positioning/blob/main/lib/positioning/advisory_lock.rb
+
+If you have any concerns or improvements please file a GitHub issue.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.