Rename "master" methods to "main" in ClusterEnvironment plugins (#10103)

* rename occurrences of master port, master address, maser node, master process

* rename properties

* add property decorators

* occurrences in docs

* update changelog

* update changelog

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* add lost method

* create deprecation

* add changelog

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix typo (but it was already there!!!)

* Apply suggestions from code review

Co-authored-by: Justus Schock <[email protected]>

* add todo

* update more occurences

* add types

* add missing import

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Justus Schock <[email protected]>

Author: 3 people

CHANGELOG.md

@@ -41,7 +41,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 
 ### Deprecated
 
--
+- Deprecated `ClusterEnvironment.master_{address,port}` in favor of `ClusterEnvironment.main_{address,port}` ([#10103](https://github.com/PyTorchLightning/pytorch-lightning/issues/10103))
 
 
 -

docs/source/clouds/cluster.rst

@@ -82,7 +82,7 @@ Once the script is setup like described in :ref:`training_script_setup`, you can
 
 Like a custom cluster, you have to ensure that there is network connectivity between the nodes with firewall rules that allow traffic flow on a specified *MASTER_PORT*.
 
-Finally, you'll need to decide which node you'd like to be the master node (*MASTER_ADDR*), and the ranks of each node (*NODE_RANK*).
+Finally, you'll need to decide which node you'd like to be the main node (*MASTER_ADDR*), and the ranks of each node (*NODE_RANK*).
 
 For example:
 
@@ -248,7 +248,7 @@ See also the multi-node examples
     # NCCL is how the nodes talk to each other
     cluster.add_command("export NCCL_DEBUG=INFO")
 
-    # setting a master port here is a good idea.
+    # setting a main port here is a good idea.
     cluster.add_command("export MASTER_PORT=%r" % PORT)
 
     # ************** DON'T FORGET THIS ***************
@@ -307,10 +307,10 @@ and node rank (node id). Here is an example of a custom
         def node_rank(self) -> int:
             return int(os.environ["NODE_RANK"])
 
-        def master_address(self) -> str:
+        def main_address(self) -> str:
             return os.environ["MASTER_ADDRESS"]
 
-        def master_port(self) -> int:
+        def main_port(self) -> int:
             return int(os.environ["MASTER_PORT"])
 
 

docs/source/common/trainer.rst

@@ -1116,11 +1116,11 @@ To define your own behavior, subclass the relevant class and pass it in. Here's
 
 
     class MyCluster(ClusterEnvironment):
-        def master_address(self):
-            return your_master_address
+        def main_address(self):
+            return your_main_address
 
-        def master_port(self):
-            return your_master_port
+        def main_port(self):
+            return your_main_port
 
         def world_size(self):
             return the_world_size

docs/source/guides/speed.rst

@@ -71,7 +71,7 @@ Prefer DDP over DP
 
 1. Copy model to device.
 2. Copy data to device.
-3. Copy outputs of each device back to master.
+3. Copy outputs of each device back to main device.
 
 Whereas :class:`~pytorch_lightning.plugins.training_type.DDPPlugin` only performs 1 transfer to sync gradients, making DDP MUCH faster than DP.
 

pytorch_lightning/accelerators/accelerator.py

@@ -479,7 +479,7 @@ def results(self) -> Any:
             This property is deprecated in v1.5 and will be removed in v1.6.
             Please call `training_type_plugin.results` directly.
 
-        In distributed training, we make sure to transfer the results to the appropriate master process.
+        In distributed training, we make sure to transfer the results to the appropriate main process.
         """
         rank_zero_deprecation(
             "`Accelerator.results` is deprecated in v1.5 and will be removed in v1.6. "

pytorch_lightning/plugins/environments/cluster_environment.py

@@ -12,23 +12,33 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 from abc import ABC, abstractmethod
+from typing import Any, Type
+
+from pytorch_lightning.utilities import rank_zero_deprecation
 
 
 class ClusterEnvironment(ABC):
     """Specification of a cluster environment."""
 
+    def __new__(cls, *args: Any, **kwargs: Any) -> "ClusterEnvironment":
+        # TODO: remove in 1.7
+        _check_for_deprecated_methods(cls)
+        return super().__new__(cls, *args, **kwargs)
+
     @property
     @abstractmethod
     def creates_processes_externally(self) -> bool:
         """Whether the environment creates the subprocesses or not."""
 
+    @property
     @abstractmethod
-    def master_address(self) -> str:
-        """The master address through which all processes connect and communicate."""
+    def main_address(self) -> str:
+        """The main address through which all processes connect and communicate."""
 
+    @property
     @abstractmethod
-    def master_port(self) -> int:
-        """An open and configured port in the master node through which all processes communicate."""
+    def main_port(self) -> int:
+        """An open and configured port in the main node through which all processes communicate."""
 
     @abstractmethod
     def world_size(self) -> int:
@@ -57,3 +67,16 @@ def node_rank(self) -> int:
     def teardown(self) -> None:
         """Clean up any state set after execution finishes."""
         pass
+
+
+def _check_for_deprecated_methods(cls: Type[ClusterEnvironment]) -> None:
+    if hasattr(cls, "master_address") and callable(cls.master_address):
+        rank_zero_deprecation(
+            f"`{cls.__name__}.master_address` has been deprecated in v1.6 and will be removed in 1.7."
+            " Implement the property `main_address` instead (do not forget to add the `@property` decorator)."
+        )
+    if hasattr(cls, "master_port") and callable(cls.master_port):
+        rank_zero_deprecation(
+            f"`{cls.__name__}.master_port` has been deprecated in v1.6 and will be removed in 1.7."
+            " Implement the property `main_port` instead (do not forget to add the `@property` decorator)."
+        )

pytorch_lightning/plugins/environments/kubeflow_environment.py

@@ -39,10 +39,12 @@ def is_using_kubeflow() -> bool:
     def creates_processes_externally(self) -> bool:
         return True
 
-    def master_address(self) -> str:
+    @property
+    def main_address(self) -> str:
         return os.environ["MASTER_ADDR"]
 
-    def master_port(self) -> int:
+    @property
+    def main_port(self) -> int:
         return int(os.environ["MASTER_PORT"])
 
     def world_size(self) -> int:

pytorch_lightning/plugins/environments/lightning_environment.py

@@ -29,14 +29,14 @@ class LightningEnvironment(ClusterEnvironment):
     2.  The user launches all processes manually or with utilities like :code:`torch.distributed.launch`.
         The appropriate environment variables need to be set, and at minimum :code:`LOCAL_RANK`.
 
-    If the master address and port are not provided, the default environment will choose them
+    If the main address and port are not provided, the default environment will choose them
     automatically. It is recommended to use this default environment for single-node distributed
     training as it provides a convenient way to launch the training script.
     """
 
     def __init__(self):
         super().__init__()
-        self._master_port = None
+        self._main_port = None
         self._global_rank: int = 0
         self._world_size: int = 1
 
@@ -49,13 +49,15 @@ def creates_processes_externally(self) -> bool:
         """
         return "LOCAL_RANK" in os.environ
 
-    def master_address(self) -> str:
+    @property
+    def main_address(self) -> str:
         return os.environ.get("MASTER_ADDR", "127.0.0.1")
 
-    def master_port(self) -> int:
-        if self._master_port is None:
-            self._master_port = os.environ.get("MASTER_PORT", find_free_network_port())
-        return int(self._master_port)
+    @property
+    def main_port(self) -> int:
+        if self._main_port is None:
+            self._main_port = os.environ.get("MASTER_PORT", find_free_network_port())
+        return int(self._main_port)
 
     def world_size(self) -> int:
         return self._world_size
@@ -85,7 +87,7 @@ def teardown(self) -> None:
 def find_free_network_port() -> int:
     """Finds a free port on localhost.
 
-    It is useful in single-node training when we don't want to connect to a real master node but have to set the
+    It is useful in single-node training when we don't want to connect to a real main node but have to set the
     `MASTER_PORT` environment variable.
     """
     s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)

pytorch_lightning/plugins/environments/lsf_environment.py

@@ -41,10 +41,10 @@ class LSFEnvironment(ClusterEnvironment):
     """
 
     def __init__(self):
-        self._master_address = self._get_master_address()
-        self._master_port = self._get_master_port()
-        log.debug(f"MASTER_ADDR: {self._master_address}")
-        log.debug(f"MASTER_PORT: {self._master_port}")
+        self._main_address = self._get_main_address()
+        self._main_port = self._get_main_port()
+        log.debug(f"MASTER_ADDR: {self._main_address}")
+        log.debug(f"MASTER_PORT: {self._main_port}")
 
     @staticmethod
     def is_using_lsf() -> bool:
@@ -56,13 +56,15 @@ def is_using_lsf() -> bool:
     def creates_processes_externally(self) -> bool:
         return True
 
-    def master_address(self):
-        """The master address is read from a list of hosts contained in the environment variable `LSB_HOSTS`."""
-        return self._master_address
+    @property
+    def main_address(self) -> str:
+        """The main address is read from a list of hosts contained in the environment variable `LSB_HOSTS`."""
+        return self._main_address
 
-    def master_port(self):
-        """THe master port gets calculated from the LSF job ID."""
-        return self._master_port
+    @property
+    def main_port(self) -> int:
+        """The main port gets calculated from the LSF job ID."""
+        return self._main_port
 
     def world_size(self):
         """The world size is read from the environment variable `JSM_NAMESPACE_SIZE`."""
@@ -127,17 +129,17 @@ def _read_hosts():
             )
         return hosts
 
-    def _get_master_address(self):
+    def _get_main_address(self) -> str:
         hosts = self._read_hosts()
         return hosts[1]
 
     @staticmethod
-    def _get_master_port():
-        """A helper function for accessing the master port.
+    def _get_main_port() -> int:
+        """A helper function for accessing the main port.
 
-        Uses the LSF job ID so all ranks can compute the master port.
+        Uses the LSF job ID so all ranks can compute the main port.
         """
-        # check for user-specified master port
+        # check for user-specified main port
         port = os.environ.get("MASTER_PORT")
         if not port:
             jobid = os.environ.get("LSB_JOBID")
@@ -146,7 +148,7 @@ def _get_master_port():
             port = int(jobid)
             # all ports should be in the 10k+ range
             port = int(port) % 1000 + 10000
-            log.debug(f"calculated LSF master port: {port}")
+            log.debug(f"calculated LSF main port: {port}")
         else:
-            log.debug(f"using externally specified master port: {port}")
+            log.debug(f"using externally specified main port: {port}")
         return int(port)

pytorch_lightning/plugins/environments/slurm_environment.py

@@ -28,7 +28,8 @@ class SLURMEnvironment(ClusterEnvironment):
     def creates_processes_externally(self) -> bool:
         return True
 
-    def master_address(self) -> str:
+    @property
+    def main_address(self) -> str:
         # figure out the root node addr
         slurm_nodelist = os.environ.get("SLURM_NODELIST")
         if slurm_nodelist:
@@ -41,7 +42,8 @@ def master_address(self) -> str:
         log.debug(f"MASTER_ADDR: {os.environ['MASTER_ADDR']}")
         return root_node
 
-    def master_port(self) -> int:
+    @property
+    def main_port(self) -> int:
         # -----------------------
         # SLURM JOB = PORT number
         # -----------------------