Add a note to the ensure_dirs() docstring about atomic directory creation.

diff --git a/pym/portage/util/__init__.py b/pym/portage/util/__init__.py
index aa37e8c3c8f697fed14a8e3a27a84161bdfbe06c..ff6302e60d059ac70e68d8bf2d0539ea8c82d404 100644 (file)
--- a/pym/portage/util/__init__.py
+++ b/pym/portage/util/__init__.py
@@ -1045,7 +1045,12 @@ def write_atomic(file_path, content, **kwargs):
 def ensure_dirs(dir_path, **kwargs):
        """Create a directory and call apply_permissions.
        Returns True if a directory is created or the permissions needed to be
-       modified, and False otherwise."""
+       modified, and False otherwise.
+
+       This function's handling of EEXIST errors makes it useful for atomic
+       directory creation, in which multiple processes may be competing to
+       create the same directory.
+       """
 
        created_dir = False