2.0/rpc.html



<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta name="robots" content="noindex">
  <meta charset="utf-8">
  <meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>Distributed RPC Framework &mdash; PyTorch 2.0 documentation</title>
  

    <link rel="canonical" href="https://pytorch.org/docs/stable/rpc.html"/>
  

  <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
  <!-- <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> -->
  <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
  <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
  <link rel="stylesheet" href="_static/copybutton.css" type="text/css" />
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.10.0-beta/dist/katex.min.css" type="text/css" />
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.13.11/dist/katex.min.css" type="text/css" />
  <link rel="stylesheet" href="_static/katex-math.css" type="text/css" />
  <link rel="stylesheet" href="_static/sphinx-dropdown.css" type="text/css" />
  <link rel="stylesheet" href="_static/panels-bootstrap.min.css" type="text/css" />
  <link rel="stylesheet" href="_static/css/jit.css" type="text/css" />
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Remote Reference Protocol" href="rpc/rref.html" />
    <link rel="prev" title="torch.ao.ns._numeric_suite_fx" href="torch.ao.ns._numeric_suite_fx.html" />


  <!-- Google Analytics -->
  
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-117752657-2"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());

      gtag('config', 'UA-117752657-2');
    </script>
  
  <!-- End Google Analytics -->
  

  <script src="_static/js/modernizr.min.js"></script>

  <!-- Preload the theme fonts -->

<link rel="preload" href="_static/fonts/FreightSans/freight-sans-book.woff2" as="font" type="font/woff2" crossorigin="anonymous">
<link rel="preload" href="_static/fonts/FreightSans/freight-sans-medium.woff2" as="font" type="font/woff2" crossorigin="anonymous">
<link rel="preload" href="_static/fonts/IBMPlexMono/IBMPlexMono-Medium.woff2" as="font" type="font/woff2" crossorigin="anonymous">
<link rel="preload" href="_static/fonts/FreightSans/freight-sans-bold.woff2" as="font" type="font/woff2" crossorigin="anonymous">
<link rel="preload" href="_static/fonts/FreightSans/freight-sans-medium-italic.woff2" as="font" type="font/woff2" crossorigin="anonymous">
<link rel="preload" href="_static/fonts/IBMPlexMono/IBMPlexMono-SemiBold.woff2" as="font" type="font/woff2" crossorigin="anonymous">

<!-- Preload the katex fonts -->

<link rel="preload" href="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/fonts/KaTeX_Math-Italic.woff2" as="font" type="font/woff2" crossorigin="anonymous">
<link rel="preload" href="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/fonts/KaTeX_Main-Regular.woff2" as="font" type="font/woff2" crossorigin="anonymous">
<link rel="preload" href="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/fonts/KaTeX_Main-Bold.woff2" as="font" type="font/woff2" crossorigin="anonymous">
<link rel="preload" href="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/fonts/KaTeX_Size1-Regular.woff2" as="font" type="font/woff2" crossorigin="anonymous">
<link rel="preload" href="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/fonts/KaTeX_Size4-Regular.woff2" as="font" type="font/woff2" crossorigin="anonymous">
<link rel="preload" href="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/fonts/KaTeX_Size2-Regular.woff2" as="font" type="font/woff2" crossorigin="anonymous">
<link rel="preload" href="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/fonts/KaTeX_Size3-Regular.woff2" as="font" type="font/woff2" crossorigin="anonymous">
<link rel="preload" href="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/fonts/KaTeX_Caligraphic-Regular.woff2" as="font" type="font/woff2" crossorigin="anonymous">
  <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.15.2/css/all.css" integrity="sha384-vSIIfh2YWi9wW0r9iZe7RJPrKwp6bG+s9QZMoITbCckVJqGCCRhc+ccxNcdpHuYu" crossorigin="anonymous">
</head>

<div class="container-fluid header-holder tutorials-header" id="header-holder">
  <div class="container">
    <div class="header-container">
      <a class="header-logo" href="https://pytorch.org/" aria-label="PyTorch"></a>

      <div class="main-menu">
        <ul>
          <li>
            <a href="https://pytorch.org/get-started">Get Started</a>
          </li>

          <li>
            <a href="https://pytorch.org/ecosystem">Ecosystem</a>
          </li>

          <li>
            <a href="https://pytorch.org/mobile">Mobile</a>
          </li>

          <li>
            <a href="https://pytorch.org/blog/">Blog</a>
          </li>

          <li>
            <a href="https://pytorch.org/tutorials">Tutorials</a>
          </li>

          <li class="active docs-active">
            <div id="resourcesDropdownButton" data-toggle="resources-dropdown" class="resources-dropdown">
              <a class="resource-option with-down-orange-arrow">
                Docs
              </a>
              <div class="resources-dropdown-menu">
                <a class="doc-dropdown-option nav-dropdown-item" href="https://pytorch.org/docs/stable/index.html">
                  <span class="dropdown-title">PyTorch</span>
                  <p></p>
                </a>
                <a class="doc-dropdown-option nav-dropdown-item" href="https://pytorch.org/audio/stable/index.html">
                  <span class="dropdown-title">torchaudio</span>
                  <p></p>
                </a>
                <a class="doc-dropdown-option nav-dropdown-item" href="https://pytorch.org/text/stable/index.html">
                  <span class="dropdown-title">torchtext</span>
                  <p></p>
                </a>
                <a class="doc-dropdown-option nav-dropdown-item" href="https://pytorch.org/vision/stable/index.html">
                  <span class="dropdown-title">torchvision</span>
                  <p></p>
                </a>
                <a class="doc-dropdown-option nav-dropdown-item" href="https://pytorch.org/torcharrow">
                  <span class="dropdown-title">torcharrow</span>
                  <p></p>
                </a>
                <a class="doc-dropdown-option nav-dropdown-item" href="https://pytorch.org/data">
                  <span class="dropdown-title">TorchData</span>
                  <p></p>
                </a>
                <a class="doc-dropdown-option nav-dropdown-item" href="https://pytorch.org/torchrec">
                  <span class="dropdown-title">TorchRec</span>
                  <p></p>
                </a>
                <a class="doc-dropdown-option nav-dropdown-item" href="https://pytorch.org/serve/">
                  <span class="dropdown-title">TorchServe</span>
                  <p></p>
                </a>
                <a class="doc-dropdown-option nav-dropdown-item" href="https://pytorch.org/torchx/">
                  <span class="dropdown-title">TorchX</span>
                  <p></p>
                </a>
                <a class="doc-dropdown-option nav-dropdown-item" href="https://pytorch.org/xla">
                  <span class="dropdown-title">PyTorch on XLA Devices</span>
                  <p></p>
                </a>
            </div>
          </li>

          <li>
            <div id="resourcesDropdownButton" data-toggle="resources-dropdown" class="resources-dropdown">
              <a class="resource-option with-down-arrow">
                Resources
              </a>
              <div class="resources-dropdown-menu">
                <a class="nav-dropdown-item" href="https://pytorch.org/features">
                  <span class="dropdown-title">About</span>
                  <p>Learn about PyTorch’s features and capabilities</p>
                </a>
                <a class="nav-dropdown-item" href="https://pytorch.org/foundation">
                  <span class="dropdown-title">PyTorch Foundation</span>
                  <p>Learn about the PyTorch foundation</p>
                </a>
                <a class="nav-dropdown-item" href="https://pytorch.org/#community-module">
                  <span class="dropdown-title">Community</span>
                  <p>Join the PyTorch developer community to contribute, learn, and get your questions answered.</p>
                </a>
                <a class="nav-dropdown-item" href="https://pytorch.org/community-stories">
                  <span class="dropdown-title">Community Stories</span>
                  <p>Learn how our community solves real, everyday machine learning problems with PyTorch.</p>
                </a>
                <a class="nav-dropdown-item" href="https://pytorch.org/resources">
                  <span class="dropdown-title">Developer Resources</span>
                  <p>Find resources and get questions answered</p>
                </a>
                <a class="nav-dropdown-item" href="https://pytorch.org/events">
                  <span class="dropdown-title">Events</span>
                  <p>Find events, webinars, and podcasts</p>
                </a>
                <a class="nav-dropdown-item" href="https://discuss.pytorch.org/" target="_blank">
                  <span class="dropdown-title">Forums</span>
                  <p>A place to discuss PyTorch code, issues, install, research</p>
                </a>
                <a class="nav-dropdown-item" href="https://pytorch.org/hub">
                  <span class="dropdown-title">Models (Beta)</span>
                  <p>Discover, publish, and reuse pre-trained models</p>
                </a>
              </div>
            </div>
          </li>

          <li>
            <a href="https://github.com/pytorch/pytorch">GitHub</a>
          </li>
        </ul>
      </div>

      <a class="main-menu-open-button" href="#" data-behavior="open-mobile-menu"></a>
    </div>
  </div>
</div>

<body class="pytorch-body">

   
    <div class="table-of-contents-link-wrapper">
      <span>Table of Contents</span>
      <a href="#" class="toggle-table-of-contents" data-behavior="toggle-table-of-contents"></a>
    </div>

    <nav data-toggle="wy-nav-shift" class="pytorch-left-menu" id="pytorch-left-menu">
      <div class="pytorch-side-scroll">
        <div class="pytorch-menu pytorch-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          <div class="pytorch-left-menu-search">
            
    <div class="version">
      <a href='https://pytorch.org/docs/versions.html'>2.0 &#x25BC</a>
    </div>
    

<div role="search">
  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
    <input type="text" name="q" placeholder="Search Docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

          </div>

          
              <p class="caption" role="heading"><span class="caption-text">Community</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="community/build_ci_governance.html">PyTorch Governance | Build + CI</a></li>
<li class="toctree-l1"><a class="reference internal" href="community/contribution_guide.html">PyTorch Contribution Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="community/design.html">PyTorch Design Philosophy</a></li>
<li class="toctree-l1"><a class="reference internal" href="community/governance.html">PyTorch Governance | Mechanics</a></li>
<li class="toctree-l1"><a class="reference internal" href="community/persons_of_interest.html">PyTorch Governance | Maintainers</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Developer Notes</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="notes/amp_examples.html">CUDA Automatic Mixed Precision examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="notes/autograd.html">Autograd mechanics</a></li>
<li class="toctree-l1"><a class="reference internal" href="notes/broadcasting.html">Broadcasting semantics</a></li>
<li class="toctree-l1"><a class="reference internal" href="notes/cpu_threading_torchscript_inference.html">CPU threading and TorchScript inference</a></li>
<li class="toctree-l1"><a class="reference internal" href="notes/cuda.html">CUDA semantics</a></li>
<li class="toctree-l1"><a class="reference internal" href="notes/ddp.html">Distributed Data Parallel</a></li>
<li class="toctree-l1"><a class="reference internal" href="notes/extending.html">Extending PyTorch</a></li>
<li class="toctree-l1"><a class="reference internal" href="notes/extending.func.html">Extending torch.func with autograd.Function</a></li>
<li class="toctree-l1"><a class="reference internal" href="notes/faq.html">Frequently Asked Questions</a></li>
<li class="toctree-l1"><a class="reference internal" href="notes/gradcheck.html">Gradcheck mechanics</a></li>
<li class="toctree-l1"><a class="reference internal" href="notes/hip.html">HIP (ROCm) semantics</a></li>
<li class="toctree-l1"><a class="reference internal" href="notes/large_scale_deployments.html">Features for large-scale deployments</a></li>
<li class="toctree-l1"><a class="reference internal" href="notes/modules.html">Modules</a></li>
<li class="toctree-l1"><a class="reference internal" href="notes/mps.html">MPS backend</a></li>
<li class="toctree-l1"><a class="reference internal" href="notes/multiprocessing.html">Multiprocessing best practices</a></li>
<li class="toctree-l1"><a class="reference internal" href="notes/numerical_accuracy.html">Numerical accuracy</a></li>
<li class="toctree-l1"><a class="reference internal" href="notes/randomness.html">Reproducibility</a></li>
<li class="toctree-l1"><a class="reference internal" href="notes/serialization.html">Serialization semantics</a></li>
<li class="toctree-l1"><a class="reference internal" href="notes/windows.html">Windows FAQ</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">torch.compile</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="dynamo/index.html">TorchDynamo Overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="dynamo/installation.html">Installing TorchDynamo</a></li>
<li class="toctree-l1"><a class="reference internal" href="dynamo/get-started.html">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="dynamo/guards-overview.html">Guards Overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="dynamo/custom-backends.html">Custom Backends</a></li>
<li class="toctree-l1"><a class="reference internal" href="dynamo/deep-dive.html">TorchDynamo Deeper Dive</a></li>
<li class="toctree-l1"><a class="reference internal" href="dynamo/troubleshooting.html">TorchDynamo Troubleshooting</a></li>
<li class="toctree-l1"><a class="reference internal" href="dynamo/faq.html">Frequently Asked Questions</a></li>
<li class="toctree-l1"><a class="reference internal" href="ir.html">IRs</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Language Bindings</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="cpp_index.html">C++</a></li>
<li class="toctree-l1"><a class="reference external" href="https://pytorch.org/javadoc/">Javadoc</a></li>
<li class="toctree-l1"><a class="reference internal" href="deploy.html">torch::deploy</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Python API</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="torch.html">torch</a></li>
<li class="toctree-l1"><a class="reference internal" href="nn.html">torch.nn</a></li>
<li class="toctree-l1"><a class="reference internal" href="nn.functional.html">torch.nn.functional</a></li>
<li class="toctree-l1"><a class="reference internal" href="tensors.html">torch.Tensor</a></li>
<li class="toctree-l1"><a class="reference internal" href="tensor_attributes.html">Tensor Attributes</a></li>
<li class="toctree-l1"><a class="reference internal" href="tensor_view.html">Tensor Views</a></li>
<li class="toctree-l1"><a class="reference internal" href="amp.html">torch.amp</a></li>
<li class="toctree-l1"><a class="reference internal" href="autograd.html">torch.autograd</a></li>
<li class="toctree-l1"><a class="reference internal" href="library.html">torch.library</a></li>
<li class="toctree-l1"><a class="reference internal" href="cuda.html">torch.cuda</a></li>
<li class="toctree-l1"><a class="reference internal" href="mps.html">torch.mps</a></li>
<li class="toctree-l1"><a class="reference internal" href="backends.html">torch.backends</a></li>
<li class="toctree-l1"><a class="reference internal" href="distributed.html">torch.distributed</a></li>
<li class="toctree-l1"><a class="reference internal" href="distributed.algorithms.join.html">torch.distributed.algorithms.join</a></li>
<li class="toctree-l1"><a class="reference internal" href="distributed.elastic.html">torch.distributed.elastic</a></li>
<li class="toctree-l1"><a class="reference internal" href="fsdp.html">torch.distributed.fsdp</a></li>
<li class="toctree-l1"><a class="reference internal" href="distributed.optim.html">torch.distributed.optim</a></li>
<li class="toctree-l1"><a class="reference internal" href="distributed.tensor.parallel.html">torch.distributed.tensor.parallel</a></li>
<li class="toctree-l1"><a class="reference internal" href="distributed.checkpoint.html">torch.distributed.checkpoint</a></li>
<li class="toctree-l1"><a class="reference internal" href="distributions.html">torch.distributions</a></li>
<li class="toctree-l1"><a class="reference internal" href="_dynamo.html">torch._dynamo</a></li>
<li class="toctree-l1"><a class="reference internal" href="fft.html">torch.fft</a></li>
<li class="toctree-l1"><a class="reference internal" href="func.html">torch.func</a></li>
<li class="toctree-l1"><a class="reference internal" href="futures.html">torch.futures</a></li>
<li class="toctree-l1"><a class="reference internal" href="fx.html">torch.fx</a></li>
<li class="toctree-l1"><a class="reference internal" href="hub.html">torch.hub</a></li>
<li class="toctree-l1"><a class="reference internal" href="jit.html">torch.jit</a></li>
<li class="toctree-l1"><a class="reference internal" href="linalg.html">torch.linalg</a></li>
<li class="toctree-l1"><a class="reference internal" href="monitor.html">torch.monitor</a></li>
<li class="toctree-l1"><a class="reference internal" href="signal.html">torch.signal</a></li>
<li class="toctree-l1"><a class="reference internal" href="special.html">torch.special</a></li>
<li class="toctree-l1"><a class="reference internal" href="torch.overrides.html">torch.overrides</a></li>
<li class="toctree-l1"><a class="reference internal" href="package.html">torch.package</a></li>
<li class="toctree-l1"><a class="reference internal" href="profiler.html">torch.profiler</a></li>
<li class="toctree-l1"><a class="reference internal" href="nn.init.html">torch.nn.init</a></li>
<li class="toctree-l1"><a class="reference internal" href="onnx.html">torch.onnx</a></li>
<li class="toctree-l1"><a class="reference internal" href="onnx_diagnostics.html">torch.onnx diagnostics</a></li>
<li class="toctree-l1"><a class="reference internal" href="optim.html">torch.optim</a></li>
<li class="toctree-l1"><a class="reference internal" href="complex_numbers.html">Complex Numbers</a></li>
<li class="toctree-l1"><a class="reference internal" href="ddp_comm_hooks.html">DDP Communication Hooks</a></li>
<li class="toctree-l1"><a class="reference internal" href="pipeline.html">Pipeline Parallelism</a></li>
<li class="toctree-l1"><a class="reference internal" href="quantization.html">Quantization</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Distributed RPC Framework</a></li>
<li class="toctree-l1"><a class="reference internal" href="random.html">torch.random</a></li>
<li class="toctree-l1"><a class="reference internal" href="masked.html">torch.masked</a></li>
<li class="toctree-l1"><a class="reference internal" href="nested.html">torch.nested</a></li>
<li class="toctree-l1"><a class="reference internal" href="sparse.html">torch.sparse</a></li>
<li class="toctree-l1"><a class="reference internal" href="storage.html">torch.Storage</a></li>
<li class="toctree-l1"><a class="reference internal" href="testing.html">torch.testing</a></li>
<li class="toctree-l1"><a class="reference internal" href="benchmark_utils.html">torch.utils.benchmark</a></li>
<li class="toctree-l1"><a class="reference internal" href="bottleneck.html">torch.utils.bottleneck</a></li>
<li class="toctree-l1"><a class="reference internal" href="checkpoint.html">torch.utils.checkpoint</a></li>
<li class="toctree-l1"><a class="reference internal" href="cpp_extension.html">torch.utils.cpp_extension</a></li>
<li class="toctree-l1"><a class="reference internal" href="data.html">torch.utils.data</a></li>
<li class="toctree-l1"><a class="reference internal" href="jit_utils.html">torch.utils.jit</a></li>
<li class="toctree-l1"><a class="reference internal" href="dlpack.html">torch.utils.dlpack</a></li>
<li class="toctree-l1"><a class="reference internal" href="mobile_optimizer.html">torch.utils.mobile_optimizer</a></li>
<li class="toctree-l1"><a class="reference internal" href="model_zoo.html">torch.utils.model_zoo</a></li>
<li class="toctree-l1"><a class="reference internal" href="tensorboard.html">torch.utils.tensorboard</a></li>
<li class="toctree-l1"><a class="reference internal" href="type_info.html">Type Info</a></li>
<li class="toctree-l1"><a class="reference internal" href="named_tensor.html">Named Tensors</a></li>
<li class="toctree-l1"><a class="reference internal" href="name_inference.html">Named Tensors operator coverage</a></li>
<li class="toctree-l1"><a class="reference internal" href="config_mod.html">torch.__config__</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Libraries</span></p>
<ul>
<li class="toctree-l1"><a class="reference external" href="https://pytorch.org/audio/stable">torchaudio</a></li>
<li class="toctree-l1"><a class="reference external" href="https://pytorch.org/data">TorchData</a></li>
<li class="toctree-l1"><a class="reference external" href="https://pytorch.org/torchrec">TorchRec</a></li>
<li class="toctree-l1"><a class="reference external" href="https://pytorch.org/serve">TorchServe</a></li>
<li class="toctree-l1"><a class="reference external" href="https://pytorch.org/text/stable">torchtext</a></li>
<li class="toctree-l1"><a class="reference external" href="https://pytorch.org/vision/stable">torchvision</a></li>
<li class="toctree-l1"><a class="reference external" href="https://pytorch.org/xla/">PyTorch on XLA Devices</a></li>
</ul>

            
        </div>
      </div>
    </nav>

    <div class="pytorch-container">
      <div class="pytorch-page-level-bar" id="pytorch-page-level-bar">
        <div class="pytorch-breadcrumbs-wrapper">
          

<div role="navigation" aria-label="breadcrumbs navigation">

  <ul class="pytorch-breadcrumbs">
    
      <li>
        <a href="index.html">
          
            Docs
          
        </a> &gt;
      </li>

        
      <li>Distributed RPC Framework</li>
    
    
      <li class="pytorch-breadcrumbs-aside">
        
            
            <a href="_sources/rpc.rst.txt" rel="nofollow"><img src="_static/images/view-page-source-icon.svg"></a>
          
        
      </li>
    
  </ul>

  
</div>
        </div>

        <div class="pytorch-shortcuts-wrapper" id="pytorch-shortcuts-wrapper">
          Shortcuts
        </div>
      </div>

      <section data-toggle="wy-nav-shift" id="pytorch-content-wrap" class="pytorch-content-wrap">
        <div class="pytorch-content-left">

        
          <div class="rst-content">
          
            <div role="main" class="main-content" itemscope="itemscope" itemtype="http://schema.org/Article">
             <article itemprop="articleBody" id="pytorch-article" class="pytorch-article">
              
  <section id="distributed-rpc-framework">
<span id="id1"></span><h1>Distributed RPC Framework<a class="headerlink" href="#distributed-rpc-framework" title="Permalink to this heading">¶</a></h1>
<p>The distributed RPC framework provides mechanisms for multi-machine model
training through a set of primitives to allow for remote communication, and a
higher-level API to automatically differentiate models split across several
machines.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>APIs in the RPC package are stable. There are multiple ongoing work items
to improve performance and error handling, which will ship in future releases.</p>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>CUDA support was introduced in PyTorch 1.9 and is still a <strong>beta</strong> feature.
Not all features of the RPC package are yet compatible with CUDA support and
thus their use is discouraged. These unsupported features include: RRefs,
JIT compatibility, dist autograd and dist optimizer, and profiling. These
shortcomings will be addressed in future releases.</p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Please refer to <a class="reference external" href="https://pytorch.org/tutorials/beginner/dist_overview.html">PyTorch Distributed Overview</a>
for a brief introduction to all features related to distributed training.</p>
</div>
<section id="basics">
<h2>Basics<a class="headerlink" href="#basics" title="Permalink to this heading">¶</a></h2>
<p>The distributed RPC framework makes it easy to run functions remotely, supports
referencing remote objects without copying the real data around, and provides
autograd and optimizer APIs to transparently run backward and update parameters
across RPC boundaries. These features can be categorized into four sets of APIs.</p>
<ol class="arabic simple">
<li><p><strong>Remote Procedure Call (RPC)</strong> supports running a function on the specified
destination worker with the given arguments and getting the return value back
or creating a reference to the return value. There are three main RPC APIs:
<a class="reference internal" href="#torch.distributed.rpc.rpc_sync" title="torch.distributed.rpc.rpc_sync"><code class="xref py py-meth docutils literal notranslate"><span class="pre">rpc_sync()</span></code></a> (synchronous),
<a class="reference internal" href="#torch.distributed.rpc.rpc_async" title="torch.distributed.rpc.rpc_async"><code class="xref py py-meth docutils literal notranslate"><span class="pre">rpc_async()</span></code></a> (asynchronous), and
<a class="reference internal" href="#torch.distributed.rpc.remote" title="torch.distributed.rpc.remote"><code class="xref py py-meth docutils literal notranslate"><span class="pre">remote()</span></code></a> (asynchronous and returns a reference
to the remote return value). Use the synchronous API if the user code cannot
proceed without the return value. Otherwise, use the asynchronous API to get
a future, and wait on the future when the return value is needed on the
caller. The <a class="reference internal" href="#torch.distributed.rpc.remote" title="torch.distributed.rpc.remote"><code class="xref py py-meth docutils literal notranslate"><span class="pre">remote()</span></code></a> API is useful when the
requirement is to create something remotely but never need to fetch it to
the caller. Imagine the case that a driver process is setting up a parameter
server and a trainer. The driver can create an embedding table on the
parameter server and then share the reference to the embedding table with the
trainer, but itself will never use the embedding table locally. In this case,
<a class="reference internal" href="#torch.distributed.rpc.rpc_sync" title="torch.distributed.rpc.rpc_sync"><code class="xref py py-meth docutils literal notranslate"><span class="pre">rpc_sync()</span></code></a> and
<a class="reference internal" href="#torch.distributed.rpc.rpc_async" title="torch.distributed.rpc.rpc_async"><code class="xref py py-meth docutils literal notranslate"><span class="pre">rpc_async()</span></code></a> are no longer appropriate, as they
always imply that the return value will be returned to the caller
immediately or in the future.</p></li>
<li><p><strong>Remote Reference (RRef)</strong> serves as a distributed shared pointer to a local
or remote object. It can be shared with other workers and reference counting
will be handled transparently. Each RRef only has one owner and the object
only lives on that owner. Non-owner workers holding RRefs can get copies of
the object from the owner by explicitly requesting it. This is useful when
a worker needs to access some data object, but itself is neither the creator
(the caller of <a class="reference internal" href="#torch.distributed.rpc.remote" title="torch.distributed.rpc.remote"><code class="xref py py-meth docutils literal notranslate"><span class="pre">remote()</span></code></a>) or the owner of the
object. The distributed optimizer, as we will discuss below, is one example
of such use cases.</p></li>
<li><p><strong>Distributed Autograd</strong> stitches together local autograd engines on all the
workers involved in the forward pass, and automatically reach out to them
during the backward pass to compute gradients. This is especially helpful if
the forward pass needs to span multiple machines when conducting, e.g.,
distributed model parallel training, parameter-server training, etc. With
this feature, user code no longer needs to worry about how to send gradients
across RPC boundaries and in which order should the local autograd engines
be launched, which can become quite complicated where there are nested and
inter-dependent RPC calls in the forward pass.</p></li>
<li><p><strong>Distributed Optimizer</strong>’s constructor takes a
<a class="reference internal" href="optim.html#torch.optim.Optimizer" title="torch.optim.Optimizer"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Optimizer()</span></code></a> (e.g., <a class="reference internal" href="generated/torch.optim.SGD.html#torch.optim.SGD" title="torch.optim.SGD"><code class="xref py py-meth docutils literal notranslate"><span class="pre">SGD()</span></code></a>,
<a class="reference internal" href="generated/torch.optim.Adagrad.html#torch.optim.Adagrad" title="torch.optim.Adagrad"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Adagrad()</span></code></a>, etc.) and a list of parameter RRefs, creates an
<a class="reference internal" href="optim.html#torch.optim.Optimizer" title="torch.optim.Optimizer"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Optimizer()</span></code></a> instance on each distinct RRef owner, and
updates parameters accordingly when running <code class="docutils literal notranslate"><span class="pre">step()</span></code>. When you have
distributed forward and backward passes, parameters and gradients will be
scattered across multiple workers, and hence it requires an optimizer on each
of the involved workers. Distributed Optimizer wraps all those local
optimizers into one, and provides a concise constructor and <code class="docutils literal notranslate"><span class="pre">step()</span></code> API.</p></li>
</ol>
</section>
<section id="rpc">
<span id="id2"></span><h2>RPC<a class="headerlink" href="#rpc" title="Permalink to this heading">¶</a></h2>
<p>Before using RPC and distributed autograd primitives, initialization must take
place. To initialize the RPC framework we need to use
<a class="reference internal" href="#torch.distributed.rpc.init_rpc" title="torch.distributed.rpc.init_rpc"><code class="xref py py-meth docutils literal notranslate"><span class="pre">init_rpc()</span></code></a> which would initialize the RPC
framework, RRef framework and distributed autograd.</p>
<span class="target" id="module-torch.distributed.rpc"></span><dl class="py function">
<dt class="sig sig-object py" id="torch.distributed.rpc.init_rpc">
<span class="sig-prename descclassname"><span class="pre">torch.distributed.rpc.</span></span><span class="sig-name descname"><span class="pre">init_rpc</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">backend</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">rank</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-</span> <span class="pre">1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">world_size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">rpc_backend_options</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/torch/distributed/rpc.html#init_rpc"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#torch.distributed.rpc.init_rpc" title="Permalink to this definition">¶</a></dt>
<dd><p>Initializes RPC primitives such as the local RPC agent
and distributed autograd, which immediately makes the current
process ready to send and receive RPCs.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>name</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.11)"><em>str</em></a>) – a globally unique name of this node. (e.g.,
<code class="docutils literal notranslate"><span class="pre">Trainer3</span></code>, <code class="docutils literal notranslate"><span class="pre">ParameterServer2</span></code>, <code class="docutils literal notranslate"><span class="pre">Master</span></code>, <code class="docutils literal notranslate"><span class="pre">Worker1</span></code>)
Name can only contain number, alphabet, underscore, colon,
and/or dash, and must be shorter than 128 characters.</p></li>
<li><p><strong>backend</strong> (<a class="reference internal" href="#torch.distributed.rpc.BackendType" title="torch.distributed.rpc.BackendType"><em>BackendType</em></a><em>, </em><em>optional</em>) – The type of RPC backend
implementation. Supported values is
<code class="docutils literal notranslate"><span class="pre">BackendType.TENSORPIPE</span></code> (the default).
See <a class="reference internal" href="#rpc-backends"><span class="std std-ref">Backends</span></a> for more information.</p></li>
<li><p><strong>rank</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.11)"><em>int</em></a>) – a globally unique id/rank of this node.</p></li>
<li><p><strong>world_size</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.11)"><em>int</em></a>) – The number of workers in the group.</p></li>
<li><p><strong>rpc_backend_options</strong> (<a class="reference internal" href="#torch.distributed.rpc.RpcBackendOptions" title="torch.distributed.rpc.RpcBackendOptions"><em>RpcBackendOptions</em></a><em>, </em><em>optional</em>) – The options
passed to the RpcAgent constructor. It must be an agent-specific
subclass of <a class="reference internal" href="#torch.distributed.rpc.RpcBackendOptions" title="torch.distributed.rpc.RpcBackendOptions"><code class="xref py py-class docutils literal notranslate"><span class="pre">RpcBackendOptions</span></code></a>
and contains agent-specific initialization configurations. By
default, for all agents, it sets the default timeout to 60
seconds and performs the rendezvous with an underlying process
group initialized using <code class="docutils literal notranslate"><span class="pre">init_method</span> <span class="pre">=</span> <span class="pre">&quot;env://&quot;</span></code>,
meaning that environment variables <code class="docutils literal notranslate"><span class="pre">MASTER_ADDR</span></code> and
<code class="docutils literal notranslate"><span class="pre">MASTER_PORT</span></code> need to be set properly. See
<a class="reference internal" href="#rpc-backends"><span class="std std-ref">Backends</span></a> for more information and find which options
are available.</p></li>
</ul>
</dd>
</dl>
</dd></dl>

<p>The following APIs allow users to remotely execute functions as well as create
references (RRefs) to remote data objects. In these APIs, when passing a
<code class="docutils literal notranslate"><span class="pre">Tensor</span></code> as an argument or a return value, the destination worker will try to
create a <code class="docutils literal notranslate"><span class="pre">Tensor</span></code> with the same meta (i.e., shape, stride, etc.). We
intentionally disallow transmitting CUDA tensors because it might crash if the
device lists on source and destination workers do not match. In such cases,
applications can always explicitly move the input tensors to CPU on the caller
and move it to the desired devices on the callee if necessary.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>TorchScript support in RPC is a prototype feature and subject to change. Since
v1.5.0, <code class="docutils literal notranslate"><span class="pre">torch.distributed.rpc</span></code> supports calling TorchScript functions as
RPC target functions, and this will help improve parallelism on the callee
side as executing TorchScript functions does not require GIL.</p>
</div>
<dl class="py function">
<dt class="sig sig-object py" id="torch.distributed.rpc.rpc_sync">
<span class="sig-prename descclassname"><span class="pre">torch.distributed.rpc.</span></span><span class="sig-name descname"><span class="pre">rpc_sync</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">to</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">func</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">args</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">kwargs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-</span> <span class="pre">1.0</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/torch/distributed/rpc/api.html#rpc_sync"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#torch.distributed.rpc.rpc_sync" title="Permalink to this definition">¶</a></dt>
<dd><p>Make a blocking RPC call to run function <code class="docutils literal notranslate"><span class="pre">func</span></code> on worker <code class="docutils literal notranslate"><span class="pre">to</span></code>. RPC
messages are sent and received in parallel to execution of Python code. This
method is thread-safe.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>to</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.11)"><em>str</em></a><em> or </em><a class="reference internal" href="#torch.distributed.rpc.WorkerInfo" title="torch.distributed.rpc.WorkerInfo"><em>WorkerInfo</em></a><em> or </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.11)"><em>int</em></a>) – name/rank/<code class="docutils literal notranslate"><span class="pre">WorkerInfo</span></code> of the destination worker.</p></li>
<li><p><strong>func</strong> (<em>Callable</em>) – a callable function, such as Python callables, builtin
operators (e.g. <a class="reference internal" href="generated/torch.add.html#torch.add" title="torch.add"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add()</span></code></a>) and annotated
TorchScript functions.</p></li>
<li><p><strong>args</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#tuple" title="(in Python v3.11)"><em>tuple</em></a>) – the argument tuple for the <code class="docutils literal notranslate"><span class="pre">func</span></code> invocation.</p></li>
<li><p><strong>kwargs</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#dict" title="(in Python v3.11)"><em>dict</em></a>) – is a dictionary of keyword arguments for the <code class="docutils literal notranslate"><span class="pre">func</span></code>
invocation.</p></li>
<li><p><strong>timeout</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.11)"><em>float</em></a><em>, </em><em>optional</em>) – timeout in seconds to use for this RPC. If
the RPC does not complete in this amount of
time, an exception indicating it has
timed out will be raised. A value of 0
indicates an infinite timeout, i.e. a timeout
error will never be raised. If not provided,
the default value set during initialization
or with <code class="docutils literal notranslate"><span class="pre">_set_rpc_timeout</span></code> is used.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Returns the result of running <code class="docutils literal notranslate"><span class="pre">func</span></code> with <code class="docutils literal notranslate"><span class="pre">args</span></code> and <code class="docutils literal notranslate"><span class="pre">kwargs</span></code>.</p>
</dd>
</dl>
<dl>
<dt>Example::</dt><dd><p>Make sure that <code class="docutils literal notranslate"><span class="pre">MASTER_ADDR</span></code> and <code class="docutils literal notranslate"><span class="pre">MASTER_PORT</span></code> are set properly
on both workers. Refer to <a class="reference internal" href="distributed.html#torch.distributed.init_process_group" title="torch.distributed.init_process_group"><code class="xref py py-meth docutils literal notranslate"><span class="pre">init_process_group()</span></code></a>
API for more details. For example,</p>
<p>export MASTER_ADDR=localhost
export MASTER_PORT=5678</p>
<p>Then run the following code in two different processes:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="c1"># On worker 0:</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">torch</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">torch.distributed.rpc</span> <span class="k">as</span> <span class="nn">rpc</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rpc</span><span class="o">.</span><span class="n">init_rpc</span><span class="p">(</span><span class="s2">&quot;worker0&quot;</span><span class="p">,</span> <span class="n">rank</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">world_size</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ret</span> <span class="o">=</span> <span class="n">rpc</span><span class="o">.</span><span class="n">rpc_sync</span><span class="p">(</span><span class="s2">&quot;worker1&quot;</span><span class="p">,</span> <span class="n">torch</span><span class="o">.</span><span class="n">add</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">torch</span><span class="o">.</span><span class="n">ones</span><span class="p">(</span><span class="mi">2</span><span class="p">),</span> <span class="mi">3</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rpc</span><span class="o">.</span><span class="n">shutdown</span><span class="p">()</span>
</pre></div>
</div>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="c1"># On worker 1:</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">torch.distributed.rpc</span> <span class="k">as</span> <span class="nn">rpc</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rpc</span><span class="o">.</span><span class="n">init_rpc</span><span class="p">(</span><span class="s2">&quot;worker1&quot;</span><span class="p">,</span> <span class="n">rank</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">world_size</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rpc</span><span class="o">.</span><span class="n">shutdown</span><span class="p">()</span>
</pre></div>
</div>
<p>Below is an example of running a TorchScript function using RPC.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="c1"># On both workers:</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nd">@torch</span><span class="o">.</span><span class="n">jit</span><span class="o">.</span><span class="n">script</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">my_script_add</span><span class="p">(</span><span class="n">t1</span><span class="p">,</span> <span class="n">t2</span><span class="p">):</span>
<span class="gp">&gt;&gt;&gt; </span>   <span class="k">return</span> <span class="n">torch</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">t1</span><span class="p">,</span> <span class="n">t2</span><span class="p">)</span>
</pre></div>
</div>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="c1"># On worker 0:</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">torch.distributed.rpc</span> <span class="k">as</span> <span class="nn">rpc</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rpc</span><span class="o">.</span><span class="n">init_rpc</span><span class="p">(</span><span class="s2">&quot;worker0&quot;</span><span class="p">,</span> <span class="n">rank</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">world_size</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ret</span> <span class="o">=</span> <span class="n">rpc</span><span class="o">.</span><span class="n">rpc_sync</span><span class="p">(</span><span class="s2">&quot;worker1&quot;</span><span class="p">,</span> <span class="n">my_script_add</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">torch</span><span class="o">.</span><span class="n">ones</span><span class="p">(</span><span class="mi">2</span><span class="p">),</span> <span class="mi">3</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rpc</span><span class="o">.</span><span class="n">shutdown</span><span class="p">()</span>
</pre></div>
</div>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="c1"># On worker 1:</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">torch.distributed.rpc</span> <span class="k">as</span> <span class="nn">rpc</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rpc</span><span class="o">.</span><span class="n">init_rpc</span><span class="p">(</span><span class="s2">&quot;worker1&quot;</span><span class="p">,</span> <span class="n">rank</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">world_size</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rpc</span><span class="o">.</span><span class="n">shutdown</span><span class="p">()</span>
</pre></div>
</div>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="torch.distributed.rpc.rpc_async">
<span class="sig-prename descclassname"><span class="pre">torch.distributed.rpc.</span></span><span class="sig-name descname"><span class="pre">rpc_async</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">to</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">func</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">args</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">kwargs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-</span> <span class="pre">1.0</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/torch/distributed/rpc/api.html#rpc_async"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#torch.distributed.rpc.rpc_async" title="Permalink to this definition">¶</a></dt>
<dd><p>Make a non-blocking RPC call to run function <code class="docutils literal notranslate"><span class="pre">func</span></code> on worker <code class="docutils literal notranslate"><span class="pre">to</span></code>. RPC
messages are sent and received in parallel to execution of Python code. This
method is thread-safe. This method will immediately return a
<a class="reference internal" href="futures.html#torch.futures.Future" title="torch.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> that can be awaited on.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>to</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.11)"><em>str</em></a><em> or </em><a class="reference internal" href="#torch.distributed.rpc.WorkerInfo" title="torch.distributed.rpc.WorkerInfo"><em>WorkerInfo</em></a><em> or </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.11)"><em>int</em></a>) – name/rank/<code class="docutils literal notranslate"><span class="pre">WorkerInfo</span></code> of the destination worker.</p></li>
<li><p><strong>func</strong> (<em>Callable</em>) – a callable function, such as Python callables, builtin
operators (e.g. <a class="reference internal" href="generated/torch.add.html#torch.add" title="torch.add"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add()</span></code></a>) and annotated
TorchScript functions.</p></li>
<li><p><strong>args</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#tuple" title="(in Python v3.11)"><em>tuple</em></a>) – the argument tuple for the <code class="docutils literal notranslate"><span class="pre">func</span></code> invocation.</p></li>
<li><p><strong>kwargs</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#dict" title="(in Python v3.11)"><em>dict</em></a>) – is a dictionary of keyword arguments for the <code class="docutils literal notranslate"><span class="pre">func</span></code>
invocation.</p></li>
<li><p><strong>timeout</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.11)"><em>float</em></a><em>, </em><em>optional</em>) – timeout in seconds to use for this RPC. If
the RPC does not complete in this amount of
time, an exception indicating it has
timed out will be raised. A value of 0
indicates an infinite timeout, i.e. a timeout
error will never be raised. If not provided,
the default value set during initialization
or with <code class="docutils literal notranslate"><span class="pre">_set_rpc_timeout</span></code> is used.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Returns a <a class="reference internal" href="futures.html#torch.futures.Future" title="torch.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> object that can be waited
on. When completed, the return value of <code class="docutils literal notranslate"><span class="pre">func</span></code> on <code class="docutils literal notranslate"><span class="pre">args</span></code> and
<code class="docutils literal notranslate"><span class="pre">kwargs</span></code> can be retrieved from the <a class="reference internal" href="futures.html#torch.futures.Future" title="torch.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a>
object.</p>
</dd>
</dl>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Using GPU tensors as arguments or return values of <code class="docutils literal notranslate"><span class="pre">func</span></code> is not
supported since we don’t support sending GPU tensors over the wire. You
need to explicitly copy GPU tensors to CPU before using them as
arguments or return values of <code class="docutils literal notranslate"><span class="pre">func</span></code>.</p>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>The <code class="docutils literal notranslate"><span class="pre">rpc_async</span></code> API does not copy storages of argument tensors until
sending them over the wire, which could be done by a different thread
depending on the RPC backend type. The caller should make sure that the
contents of those tensors stay intact until the returned
<a class="reference internal" href="futures.html#torch.futures.Future" title="torch.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> completes.</p>
</div>
<dl>
<dt>Example::</dt><dd><p>Make sure that <code class="docutils literal notranslate"><span class="pre">MASTER_ADDR</span></code> and <code class="docutils literal notranslate"><span class="pre">MASTER_PORT</span></code> are set properly
on both workers. Refer to <a class="reference internal" href="distributed.html#torch.distributed.init_process_group" title="torch.distributed.init_process_group"><code class="xref py py-meth docutils literal notranslate"><span class="pre">init_process_group()</span></code></a>
API for more details. For example,</p>
<p>export MASTER_ADDR=localhost
export MASTER_PORT=5678</p>
<p>Then run the following code in two different processes:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="c1"># On worker 0:</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">torch</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">torch.distributed.rpc</span> <span class="k">as</span> <span class="nn">rpc</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rpc</span><span class="o">.</span><span class="n">init_rpc</span><span class="p">(</span><span class="s2">&quot;worker0&quot;</span><span class="p">,</span> <span class="n">rank</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">world_size</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">fut1</span> <span class="o">=</span> <span class="n">rpc</span><span class="o">.</span><span class="n">rpc_async</span><span class="p">(</span><span class="s2">&quot;worker1&quot;</span><span class="p">,</span> <span class="n">torch</span><span class="o">.</span><span class="n">add</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">torch</span><span class="o">.</span><span class="n">ones</span><span class="p">(</span><span class="mi">2</span><span class="p">),</span> <span class="mi">3</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">fut2</span> <span class="o">=</span> <span class="n">rpc</span><span class="o">.</span><span class="n">rpc_async</span><span class="p">(</span><span class="s2">&quot;worker1&quot;</span><span class="p">,</span> <span class="nb">min</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">result</span> <span class="o">=</span> <span class="n">fut1</span><span class="o">.</span><span class="n">wait</span><span class="p">()</span> <span class="o">+</span> <span class="n">fut2</span><span class="o">.</span><span class="n">wait</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rpc</span><span class="o">.</span><span class="n">shutdown</span><span class="p">()</span>
</pre></div>
</div>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="c1"># On worker 1:</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">torch.distributed.rpc</span> <span class="k">as</span> <span class="nn">rpc</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rpc</span><span class="o">.</span><span class="n">init_rpc</span><span class="p">(</span><span class="s2">&quot;worker1&quot;</span><span class="p">,</span> <span class="n">rank</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">world_size</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rpc</span><span class="o">.</span><span class="n">shutdown</span><span class="p">()</span>
</pre></div>
</div>
<p>Below is an example of running a TorchScript function using RPC.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="c1"># On both workers:</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nd">@torch</span><span class="o">.</span><span class="n">jit</span><span class="o">.</span><span class="n">script</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">my_script_add</span><span class="p">(</span><span class="n">t1</span><span class="p">,</span> <span class="n">t2</span><span class="p">):</span>
<span class="gp">&gt;&gt;&gt; </span>   <span class="k">return</span> <span class="n">torch</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">t1</span><span class="p">,</span> <span class="n">t2</span><span class="p">)</span>
</pre></div>
</div>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="c1"># On worker 0:</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">torch.distributed.rpc</span> <span class="k">as</span> <span class="nn">rpc</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rpc</span><span class="o">.</span><span class="n">init_rpc</span><span class="p">(</span><span class="s2">&quot;worker0&quot;</span><span class="p">,</span> <span class="n">rank</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">world_size</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">fut</span> <span class="o">=</span> <span class="n">rpc</span><span class="o">.</span><span class="n">rpc_async</span><span class="p">(</span><span class="s2">&quot;worker1&quot;</span><span class="p">,</span> <span class="n">my_script_add</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">torch</span><span class="o">.</span><span class="n">ones</span><span class="p">(</span><span class="mi">2</span><span class="p">),</span> <span class="mi">3</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ret</span> <span class="o">=</span> <span class="n">fut</span><span class="o">.</span><span class="n">wait</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rpc</span><span class="o">.</span><span class="n">shutdown</span><span class="p">()</span>
</pre></div>
</div>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="c1"># On worker 1:</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">torch.distributed.rpc</span> <span class="k">as</span> <span class="nn">rpc</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rpc</span><span class="o">.</span><span class="n">init_rpc</span><span class="p">(</span><span class="s2">&quot;worker1&quot;</span><span class="p">,</span> <span class="n">rank</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">world_size</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rpc</span><span class="o">.</span><span class="n">shutdown</span><span class="p">()</span>
</pre></div>
</div>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="torch.distributed.rpc.remote">
<span class="sig-prename descclassname"><span class="pre">torch.distributed.rpc.</span></span><span class="sig-name descname"><span class="pre">remote</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">to</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">func</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">args</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">kwargs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-</span> <span class="pre">1.0</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/torch/distributed/rpc/api.html#remote"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#torch.distributed.rpc.remote" title="Permalink to this definition">¶</a></dt>
<dd><p>Make a remote call to run <code class="docutils literal notranslate"><span class="pre">func</span></code> on worker <code class="docutils literal notranslate"><span class="pre">to</span></code> and return an
<a class="reference internal" href="#torch.distributed.rpc.RRef" title="torch.distributed.rpc.RRef"><code class="xref py py-class docutils literal notranslate"><span class="pre">RRef</span></code></a> to the result value immediately.
Worker <code class="docutils literal notranslate"><span class="pre">to</span></code> will be the owner of the returned
<a class="reference internal" href="#torch.distributed.rpc.RRef" title="torch.distributed.rpc.RRef"><code class="xref py py-class docutils literal notranslate"><span class="pre">RRef</span></code></a>, and the worker calling <code class="docutils literal notranslate"><span class="pre">remote</span></code> is
a user. The owner manages the global reference count of its
<a class="reference internal" href="#torch.distributed.rpc.RRef" title="torch.distributed.rpc.RRef"><code class="xref py py-class docutils literal notranslate"><span class="pre">RRef</span></code></a>, and the owner
<a class="reference internal" href="#torch.distributed.rpc.RRef" title="torch.distributed.rpc.RRef"><code class="xref py py-class docutils literal notranslate"><span class="pre">RRef</span></code></a> is only destructed when globally there
are no living references to it.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>to</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.11)"><em>str</em></a><em> or </em><a class="reference internal" href="#torch.distributed.rpc.WorkerInfo" title="torch.distributed.rpc.WorkerInfo"><em>WorkerInfo</em></a><em> or </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.11)"><em>int</em></a>) – name/rank/<code class="docutils literal notranslate"><span class="pre">WorkerInfo</span></code> of the destination worker.</p></li>
<li><p><strong>func</strong> (<em>Callable</em>) – a callable function, such as Python callables, builtin
operators (e.g. <a class="reference internal" href="generated/torch.add.html#torch.add" title="torch.add"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add()</span></code></a>) and annotated
TorchScript functions.</p></li>
<li><p><strong>args</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#tuple" title="(in Python v3.11)"><em>tuple</em></a>) – the argument tuple for the <code class="docutils literal notranslate"><span class="pre">func</span></code> invocation.</p></li>
<li><p><strong>kwargs</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#dict" title="(in Python v3.11)"><em>dict</em></a>) – is a dictionary of keyword arguments for the <code class="docutils literal notranslate"><span class="pre">func</span></code>
invocation.</p></li>
<li><p><strong>timeout</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.11)"><em>float</em></a><em>, </em><em>optional</em>) – timeout in seconds for this remote call. If the
creation of this
<a class="reference internal" href="#torch.distributed.rpc.RRef" title="torch.distributed.rpc.RRef"><code class="xref py py-class docutils literal notranslate"><span class="pre">RRef</span></code></a> on worker
<code class="docutils literal notranslate"><span class="pre">to</span></code> is not successfully processed on this
worker within this timeout, then the next time
there is an attempt to use the RRef (such as
<code class="docutils literal notranslate"><span class="pre">to_here()</span></code>), a timeout will be raised
indicating this failure. A value of 0 indicates
an infinite timeout, i.e. a timeout error will
never be raised. If not provided, the default
value set during initialization or with
<code class="docutils literal notranslate"><span class="pre">_set_rpc_timeout</span></code> is used.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>A user <a class="reference internal" href="#torch.distributed.rpc.RRef" title="torch.distributed.rpc.RRef"><code class="xref py py-class docutils literal notranslate"><span class="pre">RRef</span></code></a> instance to the result
value. Use the blocking API <code class="xref py py-meth docutils literal notranslate"><span class="pre">torch.distributed.rpc.RRef.to_here()</span></code>
to retrieve the result value locally.</p>
</dd>
</dl>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>The <code class="docutils literal notranslate"><span class="pre">remote</span></code> API does not copy storages of argument tensors until
sending them over the wire, which could be done by a different thread
depending on the RPC backend type. The caller should make sure that the
contents of those tensors stay intact until the returned RRef is
confirmed by the owner, which can be checked using the
<code class="xref py py-meth docutils literal notranslate"><span class="pre">torch.distributed.rpc.RRef.confirmed_by_owner()</span></code> API.</p>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Errors such as timeouts for the <code class="docutils literal notranslate"><span class="pre">remote</span></code> API are handled on a
best-effort basis. This means that when remote calls initiated by
<code class="docutils literal notranslate"><span class="pre">remote</span></code> fail, such as with a timeout error, we take a best-effort
approach to error handling. This means that errors are handled and set
on the resulting RRef on an asynchronous basis. If the RRef has not been
used by the application before this handling (such as <code class="docutils literal notranslate"><span class="pre">to_here</span></code> or
fork call), then future uses of the <code class="docutils literal notranslate"><span class="pre">RRef</span></code> will appropriately raise
errors. However, it is possible that the user application will use the
<code class="docutils literal notranslate"><span class="pre">RRef</span></code> before the errors are handled. In this case, errors may not be
raised as they have not yet been handled.</p>
</div>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>Make sure that ``MASTER_ADDR`` and ``MASTER_PORT`` are set properly
on both workers. Refer to :meth:`~torch.distributed.init_process_group`
API for more details. For example,

export MASTER_ADDR=localhost
export MASTER_PORT=5678

Then run the following code in two different processes:

&gt;&gt;&gt; # On worker 0:
&gt;&gt;&gt; import torch
&gt;&gt;&gt; import torch.distributed.rpc as rpc
&gt;&gt;&gt; rpc.init_rpc(&quot;worker0&quot;, rank=0, world_size=2)
&gt;&gt;&gt; rref1 = rpc.remote(&quot;worker1&quot;, torch.add, args=(torch.ones(2), 3))
&gt;&gt;&gt; rref2 = rpc.remote(&quot;worker1&quot;, torch.add, args=(torch.ones(2), 1))
&gt;&gt;&gt; x = rref1.to_here() + rref2.to_here()
&gt;&gt;&gt; rpc.shutdown()

&gt;&gt;&gt; # On worker 1:
&gt;&gt;&gt; import torch.distributed.rpc as rpc
&gt;&gt;&gt; rpc.init_rpc(&quot;worker1&quot;, rank=1, world_size=2)
&gt;&gt;&gt; rpc.shutdown()

Below is an example of running a TorchScript function using RPC.

&gt;&gt;&gt; # On both workers:
&gt;&gt;&gt; @torch.jit.script
&gt;&gt;&gt; def my_script_add(t1, t2):
&gt;&gt;&gt;    return torch.add(t1, t2)

&gt;&gt;&gt; # On worker 0:
&gt;&gt;&gt; import torch.distributed.rpc as rpc
&gt;&gt;&gt; rpc.init_rpc(&quot;worker0&quot;, rank=0, world_size=2)
&gt;&gt;&gt; rref = rpc.remote(&quot;worker1&quot;, my_script_add, args=(torch.ones(2), 3))
&gt;&gt;&gt; rref.to_here()
&gt;&gt;&gt; rpc.shutdown()

&gt;&gt;&gt; # On worker 1:
&gt;&gt;&gt; import torch.distributed.rpc as rpc
&gt;&gt;&gt; rpc.init_rpc(&quot;worker1&quot;, rank=1, world_size=2)
&gt;&gt;&gt; rpc.shutdown()
</pre></div>
</div>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="torch.distributed.rpc.get_worker_info">
<span class="sig-prename descclassname"><span class="pre">torch.distributed.rpc.</span></span><span class="sig-name descname"><span class="pre">get_worker_info</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">worker_name</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/torch/distributed/rpc/api.html#get_worker_info"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#torch.distributed.rpc.get_worker_info" title="Permalink to this definition">¶</a></dt>
<dd><p>Get <a class="reference internal" href="#torch.distributed.rpc.WorkerInfo" title="torch.distributed.rpc.WorkerInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">WorkerInfo</span></code></a> of a given worker name.
Use this <a class="reference internal" href="#torch.distributed.rpc.WorkerInfo" title="torch.distributed.rpc.WorkerInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">WorkerInfo</span></code></a> to avoid passing an
expensive string on every invocation.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>worker_name</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.11)"><em>str</em></a>) – the string name of a worker. If <code class="docutils literal notranslate"><span class="pre">None</span></code>, return the
the id of the current worker. (default <code class="docutils literal notranslate"><span class="pre">None</span></code>)</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><a class="reference internal" href="#torch.distributed.rpc.WorkerInfo" title="torch.distributed.rpc.WorkerInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">WorkerInfo</span></code></a> instance for the given
<code class="docutils literal notranslate"><span class="pre">worker_name</span></code> or <a class="reference internal" href="#torch.distributed.rpc.WorkerInfo" title="torch.distributed.rpc.WorkerInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">WorkerInfo</span></code></a> of the
current worker if <code class="docutils literal notranslate"><span class="pre">worker_name</span></code> is <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="torch.distributed.rpc.shutdown">
<span class="sig-prename descclassname"><span class="pre">torch.distributed.rpc.</span></span><span class="sig-name descname"><span class="pre">shutdown</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">graceful</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/torch/distributed/rpc/api.html#shutdown"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#torch.distributed.rpc.shutdown" title="Permalink to this definition">¶</a></dt>
<dd><p>Perform a shutdown of the RPC agent, and then destroy the RPC agent. This
stops the local agent from accepting outstanding requests, and shuts
down the RPC framework by terminating all RPC threads. If <code class="docutils literal notranslate"><span class="pre">graceful=True</span></code>,
this will block until all local and remote RPC processes reach this method
and wait for all outstanding work to complete. Otherwise, if
<code class="docutils literal notranslate"><span class="pre">graceful=False</span></code>, this is a local shutdown, and it does not wait for other
RPC processes to reach this method.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>For <a class="reference internal" href="futures.html#torch.futures.Future" title="torch.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> objects returned by
<a class="reference internal" href="#torch.distributed.rpc.rpc_async" title="torch.distributed.rpc.rpc_async"><code class="xref py py-meth docutils literal notranslate"><span class="pre">rpc_async()</span></code></a>, <code class="docutils literal notranslate"><span class="pre">future.wait()</span></code> should not
be called after <code class="docutils literal notranslate"><span class="pre">shutdown()</span></code>.</p>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>graceful</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.11)"><em>bool</em></a>) – Whether to do a graceful shutdown or not. If True,
this will 1) wait until there is no pending system
messages for <code class="docutils literal notranslate"><span class="pre">UserRRefs</span></code> and delete them; 2) block
until all local and remote RPC processes have reached
this method and wait for all outstanding work to
complete.</p>
</dd>
</dl>
<dl>
<dt>Example::</dt><dd><p>Make sure that <code class="docutils literal notranslate"><span class="pre">MASTER_ADDR</span></code> and <code class="docutils literal notranslate"><span class="pre">MASTER_PORT</span></code> are set properly
on both workers. Refer to <a class="reference internal" href="distributed.html#torch.distributed.init_process_group" title="torch.distributed.init_process_group"><code class="xref py py-meth docutils literal notranslate"><span class="pre">init_process_group()</span></code></a>
API for more details. For example,</p>
<p>export MASTER_ADDR=localhost
export MASTER_PORT=5678</p>
<p>Then run the following code in two different processes:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="c1"># On worker 0:</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">torch</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">torch.distributed.rpc</span> <span class="k">as</span> <span class="nn">rpc</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rpc</span><span class="o">.</span><span class="n">init_rpc</span><span class="p">(</span><span class="s2">&quot;worker0&quot;</span><span class="p">,</span> <span class="n">rank</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">world_size</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># do some work</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">result</span> <span class="o">=</span> <span class="n">rpc</span><span class="o">.</span><span class="n">rpc_sync</span><span class="p">(</span><span class="s2">&quot;worker1&quot;</span><span class="p">,</span> <span class="n">torch</span><span class="o">.</span><span class="n">add</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">torch</span><span class="o">.</span><span class="n">ones</span><span class="p">(</span><span class="mi">1</span><span class="p">),</span> <span class="mi">1</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># ready to shutdown</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rpc</span><span class="o">.</span><span class="n">shutdown</span><span class="p">()</span>
</pre></div>
</div>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="c1"># On worker 1:</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">torch.distributed.rpc</span> <span class="k">as</span> <span class="nn">rpc</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rpc</span><span class="o">.</span><span class="n">init_rpc</span><span class="p">(</span><span class="s2">&quot;worker1&quot;</span><span class="p">,</span> <span class="n">rank</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">world_size</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># wait for worker 0 to finish work, and then shutdown.</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rpc</span><span class="o">.</span><span class="n">shutdown</span><span class="p">()</span>
</pre></div>
</div>
</dd>
</dl>
</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="torch.distributed.rpc.WorkerInfo">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">torch.distributed.rpc.</span></span><span class="sig-name descname"><span class="pre">WorkerInfo</span></span><a class="headerlink" href="#torch.distributed.rpc.WorkerInfo" title="Permalink to this definition">¶</a></dt>
<dd><p>A structure that encapsulates information of a worker in the system.
Contains the name and ID of the worker. This class is not meant to
be constructed directly, rather, an instance can be retrieved
through <a class="reference internal" href="#torch.distributed.rpc.get_worker_info" title="torch.distributed.rpc.get_worker_info"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_worker_info()</span></code></a> and the
result can be passed in to functions such as
<a class="reference internal" href="#torch.distributed.rpc.rpc_sync" title="torch.distributed.rpc.rpc_sync"><code class="xref py py-meth docutils literal notranslate"><span class="pre">rpc_sync()</span></code></a>, <a class="reference internal" href="#torch.distributed.rpc.rpc_async" title="torch.distributed.rpc.rpc_async"><code class="xref py py-meth docutils literal notranslate"><span class="pre">rpc_async()</span></code></a>,
<a class="reference internal" href="#torch.distributed.rpc.remote" title="torch.distributed.rpc.remote"><code class="xref py py-meth docutils literal notranslate"><span class="pre">remote()</span></code></a> to avoid copying a string on
every invocation.</p>
<dl class="py property">
<dt class="sig sig-object py" id="torch.distributed.rpc.WorkerInfo.id">
<em class="property"><span class="pre">property</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">id</span></span><a class="headerlink" href="#torch.distributed.rpc.WorkerInfo.id" title="Permalink to this definition">¶</a></dt>
<dd><p>Globally unique id to identify the worker.</p>
</dd></dl>

<dl class="py property">
<dt class="sig sig-object py" id="torch.distributed.rpc.WorkerInfo.name">
<em class="property"><span class="pre">property</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">name</span></span><a class="headerlink" href="#torch.distributed.rpc.WorkerInfo.name" title="Permalink to this definition">¶</a></dt>
<dd><p>The name of the worker.</p>
</dd></dl>

</dd></dl>

<p>The RPC package also provides decorators which allow applications to specify
how a given function should be treated on the callee side.</p>
<dl class="py function">
<dt class="sig sig-object py" id="torch.distributed.rpc.functions.async_execution">
<span class="sig-prename descclassname"><span class="pre">torch.distributed.rpc.functions.</span></span><span class="sig-name descname"><span class="pre">async_execution</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fn</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/torch/distributed/rpc/functions.html#async_execution"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#torch.distributed.rpc.functions.async_execution" title="Permalink to this definition">¶</a></dt>
<dd><p>A decorator for a function indicating that the return value of the function
is guaranteed to be a <a class="reference internal" href="futures.html#torch.futures.Future" title="torch.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> object and this
function can run asynchronously on the RPC callee. More specifically, the
callee extracts the <a class="reference internal" href="futures.html#torch.futures.Future" title="torch.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> returned by the wrapped
function and installs subsequent processing steps as a callback to that
<a class="reference internal" href="futures.html#torch.futures.Future" title="torch.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a>. The installed callback will read the value
from the <a class="reference internal" href="futures.html#torch.futures.Future" title="torch.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> when completed and send the
value back as the RPC response. That also means the returned
<a class="reference internal" href="futures.html#torch.futures.Future" title="torch.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> only exists on the callee side and is never
sent through RPC. This decorator is useful when the wrapped function’s
(<code class="docutils literal notranslate"><span class="pre">fn</span></code>) execution needs to pause and resume due to, e.g., containing
<a class="reference internal" href="#torch.distributed.rpc.rpc_async" title="torch.distributed.rpc.rpc_async"><code class="xref py py-meth docutils literal notranslate"><span class="pre">rpc_async()</span></code></a> or waiting for other signals.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>To enable asynchronous execution, applications must pass the
function object returned by this decorator to RPC APIs. If RPC detected
attributes installed by this decorator, it knows that this function
returns a <code class="docutils literal notranslate"><span class="pre">Future</span></code> object and will handle that accordingly.
However, this does not mean this decorator has to be outmost one when
defining a function. For example, when combined with <code class="docutils literal notranslate"><span class="pre">&#64;staticmethod</span></code>
or <code class="docutils literal notranslate"><span class="pre">&#64;classmethod</span></code>, <code class="docutils literal notranslate"><span class="pre">&#64;rpc.functions.async_execution</span></code> needs to be the
inner decorator to allow the target function be recognized as a static
or class function. This target function can still execute asynchronously
because, when accessed, the static or class method preserves attributes
installed by <code class="docutils literal notranslate"><span class="pre">&#64;rpc.functions.async_execution</span></code>.</p>
</div>
<dl>
<dt>Example::</dt><dd><p>The returned <a class="reference internal" href="futures.html#torch.futures.Future" title="torch.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> object can come from
<a class="reference internal" href="#torch.distributed.rpc.rpc_async" title="torch.distributed.rpc.rpc_async"><code class="xref py py-meth docutils literal notranslate"><span class="pre">rpc_async()</span></code></a>,
<a class="reference internal" href="futures.html#torch.futures.Future.then" title="torch.futures.Future.then"><code class="xref py py-meth docutils literal notranslate"><span class="pre">then()</span></code></a>, or <a class="reference internal" href="futures.html#torch.futures.Future" title="torch.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a>
constructor. The example below shows directly using the
<a class="reference internal" href="futures.html#torch.futures.Future" title="torch.futures.Future"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> returned by
<a class="reference internal" href="futures.html#torch.futures.Future.then" title="torch.futures.Future.then"><code class="xref py py-meth docutils literal notranslate"><span class="pre">then()</span></code></a>.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">torch.distributed</span> <span class="kn">import</span> <span class="n">rpc</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># omitting setup and shutdown RPC</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># On all workers</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nd">@rpc</span><span class="o">.</span><span class="n">functions</span><span class="o">.</span><span class="n">async_execution</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">async_add_chained</span><span class="p">(</span><span class="n">to</span><span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">z</span><span class="p">):</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="c1"># This function runs on &quot;worker1&quot; and returns immediately when</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="c1"># the callback is installed through the `then(cb)` API. In the</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="c1"># mean time, the `rpc_async` to &quot;worker2&quot; can run concurrently.</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="c1"># When the return value of that `rpc_async` arrives at</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="c1"># &quot;worker1&quot;, &quot;worker1&quot; will run the lambda function accordingly</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="c1"># and set the value for the previously returned `Future`, which</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="c1"># will then trigger RPC to send the result back to &quot;worker0&quot;.</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="k">return</span> <span class="n">rpc</span><span class="o">.</span><span class="n">rpc_async</span><span class="p">(</span><span class="n">to</span><span class="p">,</span> <span class="n">torch</span><span class="o">.</span><span class="n">add</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">))</span><span class="o">.</span><span class="n">then</span><span class="p">(</span>
<span class="gp">&gt;&gt;&gt; </span>        <span class="k">lambda</span> <span class="n">fut</span><span class="p">:</span> <span class="n">fut</span><span class="o">.</span><span class="n">wait</span><span class="p">()</span> <span class="o">+</span> <span class="n">z</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="p">)</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># On worker0</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ret</span> <span class="o">=</span> <span class="n">rpc</span><span class="o">.</span><span class="n">rpc_sync</span><span class="p">(</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="s2">&quot;worker1&quot;</span><span class="p">,</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">async_add_chained</span><span class="p">,</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="s2">&quot;worker2&quot;</span><span class="p">,</span> <span class="n">torch</span><span class="o">.</span><span class="n">ones</span><span class="p">(</span><span class="mi">2</span><span class="p">),</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">ret</span><span class="p">)</span>  <span class="c1"># prints tensor([3., 3.])</span>
</pre></div>
</div>
<p>When combined with TorchScript decorators, this decorator must be the
outmost one.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">torch</span> <span class="kn">import</span> <span class="n">Tensor</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">torch.futures</span> <span class="kn">import</span> <span class="n">Future</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">torch.distributed</span> <span class="kn">import</span> <span class="n">rpc</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># omitting setup and shutdown RPC</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># On all workers</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nd">@torch</span><span class="o">.</span><span class="n">jit</span><span class="o">.</span><span class="n">script</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">script_add</span><span class="p">(</span><span class="n">x</span><span class="p">:</span> <span class="n">Tensor</span><span class="p">,</span> <span class="n">y</span><span class="p">:</span> <span class="n">Tensor</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Tensor</span><span class="p">:</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="k">return</span> <span class="n">x</span> <span class="o">+</span> <span class="n">y</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nd">@rpc</span><span class="o">.</span><span class="n">functions</span><span class="o">.</span><span class="n">async_execution</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nd">@torch</span><span class="o">.</span><span class="n">jit</span><span class="o">.</span><span class="n">script</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">async_add</span><span class="p">(</span><span class="n">to</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">x</span><span class="p">:</span> <span class="n">Tensor</span><span class="p">,</span> <span class="n">y</span><span class="p">:</span> <span class="n">Tensor</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Future</span><span class="p">[</span><span class="n">Tensor</span><span class="p">]:</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="k">return</span> <span class="n">rpc</span><span class="o">.</span><span class="n">rpc_async</span><span class="p">(</span><span class="n">to</span><span class="p">,</span> <span class="n">script_add</span><span class="p">,</span> <span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">))</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># On worker0</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ret</span> <span class="o">=</span> <span class="n">rpc</span><span class="o">.</span><span class="n">rpc_sync</span><span class="p">(</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="s2">&quot;worker1&quot;</span><span class="p">,</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">async_add</span><span class="p">,</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="s2">&quot;worker2&quot;</span><span class="p">,</span> <span class="n">torch</span><span class="o">.</span><span class="n">ones</span><span class="p">(</span><span class="mi">2</span><span class="p">),</span> <span class="mi">1</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">ret</span><span class="p">)</span>  <span class="c1"># prints tensor([2., 2.])</span>
</pre></div>
</div>
<p>When combined with static or class method, this decorator must be the
inner one.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">torch.distributed</span> <span class="kn">import</span> <span class="n">rpc</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># omitting setup and shutdown RPC</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># On all workers</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">AsyncExecutionClass</span><span class="p">:</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="nd">@staticmethod</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="nd">@rpc</span><span class="o">.</span><span class="n">functions</span><span class="o">.</span><span class="n">async_execution</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="k">def</span> <span class="nf">static_async_add</span><span class="p">(</span><span class="n">to</span><span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">z</span><span class="p">):</span>
<span class="gp">&gt;&gt;&gt; </span>        <span class="k">return</span> <span class="n">rpc</span><span class="o">.</span><span class="n">rpc_async</span><span class="p">(</span><span class="n">to</span><span class="p">,</span> <span class="n">torch</span><span class="o">.</span><span class="n">add</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">))</span><span class="o">.</span><span class="n">then</span><span class="p">(</span>
<span class="gp">&gt;&gt;&gt; </span>            <span class="k">lambda</span> <span class="n">fut</span><span class="p">:</span> <span class="n">fut</span><span class="o">.</span><span class="n">wait</span><span class="p">()</span> <span class="o">+</span> <span class="n">z</span>
<span class="gp">&gt;&gt;&gt; </span>        <span class="p">)</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="nd">@classmethod</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="nd">@rpc</span><span class="o">.</span><span class="n">functions</span><span class="o">.</span><span class="n">async_execution</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="k">def</span> <span class="nf">class_async_add</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">to</span><span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">z</span><span class="p">):</span>
<span class="gp">&gt;&gt;&gt; </span>        <span class="n">ret_fut</span> <span class="o">=</span> <span class="n">torch</span><span class="o">.</span><span class="n">futures</span><span class="o">.</span><span class="n">Future</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span>        <span class="n">rpc</span><span class="o">.</span><span class="n">rpc_async</span><span class="p">(</span><span class="n">to</span><span class="p">,</span> <span class="n">torch</span><span class="o">.</span><span class="n">add</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">))</span><span class="o">.</span><span class="n">then</span><span class="p">(</span>
<span class="gp">&gt;&gt;&gt; </span>            <span class="k">lambda</span> <span class="n">fut</span><span class="p">:</span> <span class="n">ret_fut</span><span class="o">.</span><span class="n">set_result</span><span class="p">(</span><span class="n">fut</span><span class="o">.</span><span class="n">wait</span><span class="p">()</span> <span class="o">+</span> <span class="n">z</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span>        <span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span>        <span class="k">return</span> <span class="n">ret_fut</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="nd">@rpc</span><span class="o">.</span><span class="n">functions</span><span class="o">.</span><span class="n">async_execution</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="k">def</span> <span class="nf">bound_async_add</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">to</span><span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">z</span><span class="p">):</span>
<span class="gp">&gt;&gt;&gt; </span>        <span class="k">return</span> <span class="n">rpc</span><span class="o">.</span><span class="n">rpc_async</span><span class="p">(</span><span class="n">to</span><span class="p">,</span> <span class="n">torch</span><span class="o">.</span><span class="n">add</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">))</span><span class="o">.</span><span class="n">then</span><span class="p">(</span>
<span class="gp">&gt;&gt;&gt; </span>            <span class="k">lambda</span> <span class="n">fut</span><span class="p">:</span> <span class="n">fut</span><span class="o">.</span><span class="n">wait</span><span class="p">()</span> <span class="o">+</span> <span class="n">z</span>
<span class="gp">&gt;&gt;&gt; </span>        <span class="p">)</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># On worker0</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ret</span> <span class="o">=</span> <span class="n">rpc</span><span class="o">.</span><span class="n">rpc_sync</span><span class="p">(</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="s2">&quot;worker1&quot;</span><span class="p">,</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">AsyncExecutionClass</span><span class="o">.</span><span class="n">static_async_add</span><span class="p">,</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="s2">&quot;worker2&quot;</span><span class="p">,</span> <span class="n">torch</span><span class="o">.</span><span class="n">ones</span><span class="p">(</span><span class="mi">2</span><span class="p">),</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">ret</span><span class="p">)</span>  <span class="c1"># prints tensor([4., 4.])</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ret</span> <span class="o">=</span> <span class="n">rpc</span><span class="o">.</span><span class="n">rpc_sync</span><span class="p">(</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="s2">&quot;worker1&quot;</span><span class="p">,</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">AsyncExecutionClass</span><span class="o">.</span><span class="n">class_async_add</span><span class="p">,</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="s2">&quot;worker2&quot;</span><span class="p">,</span> <span class="n">torch</span><span class="o">.</span><span class="n">ones</span><span class="p">(</span><span class="mi">2</span><span class="p">),</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">ret</span><span class="p">)</span>  <span class="c1"># prints tensor([4., 4.])</span>
</pre></div>
</div>
<p>This decorator also works with RRef helpers, i.e., .
<code class="xref py py-meth docutils literal notranslate"><span class="pre">torch.distributed.rpc.RRef.rpc_sync()</span></code>,
<code class="xref py py-meth docutils literal notranslate"><span class="pre">torch.distributed.rpc.RRef.rpc_async()</span></code>, and
<code class="xref py py-meth docutils literal notranslate"><span class="pre">torch.distributed.rpc.RRef.remote()</span></code>.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">torch.distributed</span> <span class="kn">import</span> <span class="n">rpc</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># reuse the AsyncExecutionClass class above</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rref</span> <span class="o">=</span> <span class="n">rpc</span><span class="o">.</span><span class="n">remote</span><span class="p">(</span><span class="s2">&quot;worker1&quot;</span><span class="p">,</span> <span class="n">AsyncExecutionClass</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ret</span> <span class="o">=</span> <span class="n">rref</span><span class="o">.</span><span class="n">rpc_sync</span><span class="p">()</span><span class="o">.</span><span class="n">static_async_add</span><span class="p">(</span><span class="s2">&quot;worker2&quot;</span><span class="p">,</span> <span class="n">torch</span><span class="o">.</span><span class="n">ones</span><span class="p">(</span><span class="mi">2</span><span class="p">),</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">ret</span><span class="p">)</span>  <span class="c1"># prints tensor([4., 4.])</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rref</span> <span class="o">=</span> <span class="n">rpc</span><span class="o">.</span><span class="n">remote</span><span class="p">(</span><span class="s2">&quot;worker1&quot;</span><span class="p">,</span> <span class="n">AsyncExecutionClass</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ret</span> <span class="o">=</span> <span class="n">rref</span><span class="o">.</span><span class="n">rpc_async</span><span class="p">()</span><span class="o">.</span><span class="n">static_async_add</span><span class="p">(</span><span class="s2">&quot;worker2&quot;</span><span class="p">,</span> <span class="n">torch</span><span class="o">.</span><span class="n">ones</span><span class="p">(</span><span class="mi">2</span><span class="p">),</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span><span class="o">.</span><span class="n">wait</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">ret</span><span class="p">)</span>  <span class="c1"># prints tensor([4., 4.])</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rref</span> <span class="o">=</span> <span class="n">rpc</span><span class="o">.</span><span class="n">remote</span><span class="p">(</span><span class="s2">&quot;worker1&quot;</span><span class="p">,</span> <span class="n">AsyncExecutionClass</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ret</span> <span class="o">=</span> <span class="n">rref</span><span class="o">.</span><span class="n">remote</span><span class="p">()</span><span class="o">.</span><span class="n">static_async_add</span><span class="p">(</span><span class="s2">&quot;worker2&quot;</span><span class="p">,</span> <span class="n">torch</span><span class="o">.</span><span class="n">ones</span><span class="p">(</span><span class="mi">2</span><span class="p">),</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span><span class="o">.</span><span class="n">to_here</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">ret</span><span class="p">)</span>  <span class="c1"># prints tensor([4., 4.])</span>
</pre></div>
</div>
</dd>
</dl>
</dd></dl>

<section id="backends">
<span id="rpc-backends"></span><h3>Backends<a class="headerlink" href="#backends" title="Permalink to this heading">¶</a></h3>
<p>The RPC module can leverage different backends to perform the communication
between the nodes. The backend to be used can be specified in the
<a class="reference internal" href="#torch.distributed.rpc.init_rpc" title="torch.distributed.rpc.init_rpc"><code class="xref py py-func docutils literal notranslate"><span class="pre">init_rpc()</span></code></a> function, by passing a certain value of
the <a class="reference internal" href="#torch.distributed.rpc.BackendType" title="torch.distributed.rpc.BackendType"><code class="xref py py-class docutils literal notranslate"><span class="pre">BackendType</span></code></a> enum. Regardless of what backend
is used, the rest of the RPC API won’t change. Each backend also defines its own
subclass of the <a class="reference internal" href="#torch.distributed.rpc.RpcBackendOptions" title="torch.distributed.rpc.RpcBackendOptions"><code class="xref py py-class docutils literal notranslate"><span class="pre">RpcBackendOptions</span></code></a> class, an
instance of which can also be passed to <a class="reference internal" href="#torch.distributed.rpc.init_rpc" title="torch.distributed.rpc.init_rpc"><code class="xref py py-func docutils literal notranslate"><span class="pre">init_rpc()</span></code></a>
to configure the backend’s behavior.</p>
<dl class="py class">
<dt class="sig sig-object py" id="torch.distributed.rpc.BackendType">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">torch.distributed.rpc.</span></span><span class="sig-name descname"><span class="pre">BackendType</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#torch.distributed.rpc.BackendType" title="Permalink to this definition">¶</a></dt>
<dd><p>An enum class of available backends.</p>
<p>PyTorch ships with a builtin <code class="docutils literal notranslate"><span class="pre">BackendType.TENSORPIPE</span></code> backend.
Additional ones can be registered using the
<code class="xref py py-func docutils literal notranslate"><span class="pre">register_backend()</span></code> function.</p>
</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="torch.distributed.rpc.RpcBackendOptions">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">torch.distributed.rpc.</span></span><span class="sig-name descname"><span class="pre">RpcBackendOptions</span></span><a class="headerlink" href="#torch.distributed.rpc.RpcBackendOptions" title="Permalink to this definition">¶</a></dt>
<dd><p>An abstract structure encapsulating the options passed into the RPC
backend. An instance of this class can be passed in to
<a class="reference internal" href="#torch.distributed.rpc.init_rpc" title="torch.distributed.rpc.init_rpc"><code class="xref py py-meth docutils literal notranslate"><span class="pre">init_rpc()</span></code></a> in order to initialize RPC
with specific configurations, such as the RPC timeout and
<code class="docutils literal notranslate"><span class="pre">init_method</span></code> to be used.</p>
<dl class="py property">
<dt class="sig sig-object py" id="torch.distributed.rpc.RpcBackendOptions.init_method">
<em class="property"><span class="pre">property</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">init_method</span></span><a class="headerlink" href="#torch.distributed.rpc.RpcBackendOptions.init_method" title="Permalink to this definition">¶</a></dt>
<dd><p>URL specifying how to initialize the process group.
Default is <code class="docutils literal notranslate"><span class="pre">env://</span></code></p>
</dd></dl>

<dl class="py property">
<dt class="sig sig-object py" id="torch.distributed.rpc.RpcBackendOptions.rpc_timeout">
<em class="property"><span class="pre">property</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">rpc_timeout</span></span><a class="headerlink" href="#torch.distributed.rpc.RpcBackendOptions.rpc_timeout" title="Permalink to this definition">¶</a></dt>
<dd><p>A float indicating the timeout to use for all
RPCs. If an RPC does not complete in this timeframe, it will
complete with an exception indicating that it has timed out.</p>
</dd></dl>

</dd></dl>

<section id="tensorpipe-backend">
<h4>TensorPipe Backend<a class="headerlink" href="#tensorpipe-backend" title="Permalink to this heading">¶</a></h4>
<p>The TensorPipe agent, which is the default, leverages <a class="reference external" href="https://github.com/pytorch/tensorpipe">the TensorPipe library</a>, which provides a natively
point-to-point communication primitive specifically suited for machine learning
that fundamentally addresses some of the limitations of Gloo. Compared to Gloo,
it has the advantage of being asynchronous, which allows a large number of
transfers to occur simultaneously, each at their own speed, without blocking
each other. It will only open pipes between pairs of nodes when needed, on
demand, and when one node fails only its incident pipes will be closed, while
all other ones will keep working as normal. In addition, it is able to support
multiple different transports (TCP, of course, but also shared memory, NVLink,
InfiniBand, …) and can automatically detect their availability and negotiate
the best transport to use for each pipe.</p>
<p>The TensorPipe backend has been introduced in PyTorch v1.6 and is being actively
developed. At the moment, it only supports CPU tensors, with GPU support coming
soon. It comes with a TCP-based transport, just like Gloo. It is also able to
automatically chunk and multiplex large tensors over multiple sockets and
threads in order to achieve very high bandwidths. The agent will be able to pick
the best transport on its own, with no intervention required.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">os</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">torch.distributed</span> <span class="kn">import</span> <span class="n">rpc</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="p">[</span><span class="s1">&#39;MASTER_ADDR&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s1">&#39;localhost&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="p">[</span><span class="s1">&#39;MASTER_PORT&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s1">&#39;29500&#39;</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rpc</span><span class="o">.</span><span class="n">init_rpc</span><span class="p">(</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="s2">&quot;worker1&quot;</span><span class="p">,</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">rank</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">world_size</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">rpc_backend_options</span><span class="o">=</span><span class="n">rpc</span><span class="o">.</span><span class="n">TensorPipeRpcBackendOptions</span><span class="p">(</span>
<span class="gp">&gt;&gt;&gt; </span>        <span class="n">num_worker_threads</span><span class="o">=</span><span class="mi">8</span><span class="p">,</span>
<span class="gp">&gt;&gt;&gt; </span>        <span class="n">rpc_timeout</span><span class="o">=</span><span class="mi">20</span> <span class="c1"># 20 second timeout</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="p">)</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># omitting init_rpc invocation on worker2</span>
</pre></div>
</div>
<dl class="py class">
<dt class="sig sig-object py" id="torch.distributed.rpc.TensorPipeRpcBackendOptions">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">torch.distributed.rpc.</span></span><span class="sig-name descname"><span class="pre">TensorPipeRpcBackendOptions</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">num_worker_threads</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">16</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">rpc_timeout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">60.0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">init_method</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'env://'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">device_maps</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">devices</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">_transports</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">_channels</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/torch/distributed/rpc/options.html#TensorPipeRpcBackendOptions"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#torch.distributed.rpc.TensorPipeRpcBackendOptions" title="Permalink to this definition">¶</a></dt>
<dd><p>The backend options for
<code class="xref py py-class docutils literal notranslate"><span class="pre">TensorPipeAgent</span></code>, derived from
<a class="reference internal" href="#torch.distributed.rpc.RpcBackendOptions" title="torch.distributed.rpc.RpcBackendOptions"><code class="xref py py-class docutils literal notranslate"><span class="pre">RpcBackendOptions</span></code></a>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>num_worker_threads</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.11)"><em>int</em></a><em>, </em><em>optional</em>) – The number of threads in the
thread-pool used by
<code class="xref py py-class docutils literal notranslate"><span class="pre">TensorPipeAgent</span></code> to execute
requests (default: 16).</p></li>
<li><p><strong>rpc_timeout</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.11)"><em>float</em></a><em>, </em><em>optional</em>) – The default timeout, in seconds,
for RPC requests (default: 60 seconds). If the RPC has not
completed in this timeframe, an exception indicating so will
be raised. Callers can override this timeout for individual
RPCs in <a class="reference internal" href="#torch.distributed.rpc.rpc_sync" title="torch.distributed.rpc.rpc_sync"><code class="xref py py-meth docutils literal notranslate"><span class="pre">rpc_sync()</span></code></a> and
<a class="reference internal" href="#torch.distributed.rpc.rpc_async" title="torch.distributed.rpc.rpc_async"><code class="xref py py-meth docutils literal notranslate"><span class="pre">rpc_async()</span></code></a> if necessary.</p></li>
<li><p><strong>init_method</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.11)"><em>str</em></a><em>, </em><em>optional</em>) – The URL to initialize the distributed
store used for rendezvous. It takes any value accepted for the
same argument of <a class="reference internal" href="distributed.html#torch.distributed.init_process_group" title="torch.distributed.init_process_group"><code class="xref py py-meth docutils literal notranslate"><span class="pre">init_process_group()</span></code></a>
(default: <code class="docutils literal notranslate"><span class="pre">env://</span></code>).</p></li>
<li><p><strong>device_maps</strong> (<em>Dict</em><em>[</em><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.11)"><em>str</em></a><em>, </em><em>Dict</em><em>]</em><em>, </em><em>optional</em>) – Device placement mappings from
this worker to the callee. Key is the callee worker name and value
the dictionary (<code class="docutils literal notranslate"><span class="pre">Dict</span></code> of <code class="docutils literal notranslate"><span class="pre">int</span></code>, <code class="docutils literal notranslate"><span class="pre">str</span></code>, or <code class="docutils literal notranslate"><span class="pre">torch.device</span></code>)
that maps this worker’s devices to the callee worker’s devices.
(default: <code class="docutils literal notranslate"><span class="pre">None</span></code>)</p></li>
<li><p><strong>devices</strong> (List[int, str, or <code class="docutils literal notranslate"><span class="pre">torch.device</span></code>], optional) – all local
CUDA devices used by RPC agent. By Default, it will be initialized
to all local devices from its own <code class="docutils literal notranslate"><span class="pre">device_maps</span></code> and corresponding
devices from its peers’ <code class="docutils literal notranslate"><span class="pre">device_maps</span></code>. When processing CUDA RPC
requests, the agent will properly synchronize CUDA streams for
all devices in this <code class="docutils literal notranslate"><span class="pre">List</span></code>.</p></li>
</ul>
</dd>
</dl>
<dl class="py property">
<dt class="sig sig-object py" id="torch.distributed.rpc.TensorPipeRpcBackendOptions.device_maps">
<em class="property"><span class="pre">property</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">device_maps</span></span><a class="headerlink" href="#torch.distributed.rpc.TensorPipeRpcBackendOptions.device_maps" title="Permalink to this definition">¶</a></dt>
<dd><p>The device map locations.</p>
</dd></dl>

<dl class="py property">
<dt class="sig sig-object py" id="torch.distributed.rpc.TensorPipeRpcBackendOptions.devices">
<em class="property"><span class="pre">property</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">devices</span></span><a class="headerlink" href="#torch.distributed.rpc.TensorPipeRpcBackendOptions.devices" title="Permalink to this definition">¶</a></dt>
<dd><p>All devices used by the local agent.</p>
</dd></dl>

<dl class="py property">
<dt class="sig sig-object py" id="torch.distributed.rpc.TensorPipeRpcBackendOptions.init_method">
<em class="property"><span class="pre">property</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">init_method</span></span><a class="headerlink" href="#torch.distributed.rpc.TensorPipeRpcBackendOptions.init_method" title="Permalink to this definition">¶</a></dt>
<dd><p>URL specifying how to initialize the process group.
Default is <code class="docutils literal notranslate"><span class="pre">env://</span></code></p>
</dd></dl>

<dl class="py property">
<dt class="sig sig-object py" id="torch.distributed.rpc.TensorPipeRpcBackendOptions.num_worker_threads">
<em class="property"><span class="pre">property</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">num_worker_threads</span></span><a class="headerlink" href="#torch.distributed.rpc.TensorPipeRpcBackendOptions.num_worker_threads" title="Permalink to this definition">¶</a></dt>
<dd><p>The number of threads in the thread-pool used by
<code class="xref py py-class docutils literal notranslate"><span class="pre">TensorPipeAgent</span></code> to execute
requests.</p>
</dd></dl>

<dl class="py property">
<dt class="sig sig-object py" id="torch.distributed.rpc.TensorPipeRpcBackendOptions.rpc_timeout">
<em class="property"><span class="pre">property</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">rpc_timeout</span></span><a class="headerlink" href="#torch.distributed.rpc.TensorPipeRpcBackendOptions.rpc_timeout" title="Permalink to this definition">¶</a></dt>
<dd><p>A float indicating the timeout to use for all
RPCs. If an RPC does not complete in this timeframe, it will
complete with an exception indicating that it has timed out.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="torch.distributed.rpc.TensorPipeRpcBackendOptions.set_device_map">
<span class="sig-name descname"><span class="pre">set_device_map</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">to</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">device_map</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/torch/distributed/rpc/options.html#TensorPipeRpcBackendOptions.set_device_map"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#torch.distributed.rpc.TensorPipeRpcBackendOptions.set_device_map" title="Permalink to this definition">¶</a></dt>
<dd><p>Set device mapping between each RPC caller and callee pair. This
function can be called multiple times to incrementally add
device placement configurations.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>to</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.11)"><em>str</em></a>) – Callee name.</p></li>
<li><p><strong>device_map</strong> (<em>Dict of python:int</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.11)"><em>str</em></a><em>, or </em><a class="reference internal" href="tensor_attributes.html#torch.device" title="torch.device"><em>torch.device</em></a>) – Device placement
mappings from this worker to the callee. This map must be
invertible.</p></li>
</ul>
</dd>
</dl>
<p class="rubric">Example</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="c1"># both workers</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">add</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">):</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="nb">print</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>  <span class="c1"># tensor([1., 1.], device=&#39;cuda:1&#39;)</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="k">return</span> <span class="n">x</span> <span class="o">+</span> <span class="n">y</span><span class="p">,</span> <span class="p">(</span><span class="n">x</span> <span class="o">+</span> <span class="n">y</span><span class="p">)</span><span class="o">.</span><span class="n">to</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># on worker 0</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">options</span> <span class="o">=</span> <span class="n">TensorPipeRpcBackendOptions</span><span class="p">(</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">num_worker_threads</span><span class="o">=</span><span class="mi">8</span><span class="p">,</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">device_maps</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;worker1&quot;</span><span class="p">:</span> <span class="p">{</span><span class="mi">0</span><span class="p">:</span> <span class="mi">1</span><span class="p">}}</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="c1"># maps worker0&#39;s cuda:0 to worker1&#39;s cuda:1</span>
<span class="gp">&gt;&gt;&gt; </span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">options</span><span class="o">.</span><span class="n">set_device_map</span><span class="p">(</span><span class="s2">&quot;worker1&quot;</span><span class="p">,</span> <span class="p">{</span><span class="mi">1</span><span class="p">:</span> <span class="mi">2</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># maps worker0&#39;s cuda:1 to worker1&#39;s cuda:2</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rpc</span><span class="o">.</span><span class="n">init_rpc</span><span class="p">(</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="s2">&quot;worker0&quot;</span><span class="p">,</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">rank</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">world_size</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">backend</span><span class="o">=</span><span class="n">rpc</span><span class="o">.</span><span class="n">BackendType</span><span class="o">.</span><span class="n">TENSORPIPE</span><span class="p">,</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">rpc_backend_options</span><span class="o">=</span><span class="n">options</span>
<span class="gp">&gt;&gt;&gt; </span><span class="p">)</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="n">torch</span><span class="o">.</span><span class="n">ones</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rets</span> <span class="o">=</span> <span class="n">rpc</span><span class="o">.</span><span class="n">rpc_sync</span><span class="p">(</span><span class="s2">&quot;worker1&quot;</span><span class="p">,</span> <span class="n">add</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">x</span><span class="o">.</span><span class="n">to</span><span class="p">(</span><span class="mi">0</span><span class="p">),</span> <span class="mi">1</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># The first argument will be moved to cuda:1 on worker1. When</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># sending the return value back, it will follow the invert of</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># the device map, and hence will be moved back to cuda:0 and</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># cuda:1 on worker0</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">rets</span><span class="p">[</span><span class="mi">0</span><span class="p">])</span>  <span class="c1"># tensor([2., 2.], device=&#39;cuda:0&#39;)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">rets</span><span class="p">[</span><span class="mi">1</span><span class="p">])</span>  <span class="c1"># tensor([2., 2.], device=&#39;cuda:1&#39;)</span>
</pre></div>
</div>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="torch.distributed.rpc.TensorPipeRpcBackendOptions.set_devices">
<span class="sig-name descname"><span class="pre">set_devices</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">devices</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/torch/distributed/rpc/options.html#TensorPipeRpcBackendOptions.set_devices"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#torch.distributed.rpc.TensorPipeRpcBackendOptions.set_devices" title="Permalink to this definition">¶</a></dt>
<dd><p>Set local devices used by the TensorPipe RPC agent. When processing
CUDA RPC requests, the TensorPipe RPC agent will properly synchronize
CUDA streams for all devices in this <code class="docutils literal notranslate"><span class="pre">List</span></code>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>devices</strong> (<em>List of python:int</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.11)"><em>str</em></a><em>, or </em><a class="reference internal" href="tensor_attributes.html#torch.device" title="torch.device"><em>torch.device</em></a>) – local devices used by
the TensorPipe RPC agent.</p>
</dd>
</dl>
</dd></dl>

</dd></dl>

<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The RPC framework does not automatically retry any
<a class="reference internal" href="#torch.distributed.rpc.rpc_sync" title="torch.distributed.rpc.rpc_sync"><code class="xref py py-meth docutils literal notranslate"><span class="pre">rpc_sync()</span></code></a>,
<a class="reference internal" href="#torch.distributed.rpc.rpc_async" title="torch.distributed.rpc.rpc_async"><code class="xref py py-meth docutils literal notranslate"><span class="pre">rpc_async()</span></code></a> and
<a class="reference internal" href="#torch.distributed.rpc.remote" title="torch.distributed.rpc.remote"><code class="xref py py-meth docutils literal notranslate"><span class="pre">remote()</span></code></a> calls. The reason being that there is
no way the RPC framework can determine whether an operation is idempotent or
not and whether it is safe to retry. As a result, it is the application’s
responsibility to deal with failures and retry if necessary. RPC communication
is based on TCP and as a result failures could happen due to network failures
or intermittent network connectivity issues. In such scenarios, the application
needs to retry appropriately with reasonable backoffs to ensure the network
isn’t overwhelmed by aggressive retries.</p>
</div>
</section>
</section>
</section>
<section id="rref">
<span id="id3"></span><h2>RRef<a class="headerlink" href="#rref" title="Permalink to this heading">¶</a></h2>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>RRefs are not currently supported when using CUDA tensors</p>
</div>
<p>An <code class="docutils literal notranslate"><span class="pre">RRef</span></code> (Remote REFerence) is a reference to a value of some type <code class="docutils literal notranslate"><span class="pre">T</span></code>
(e.g. <code class="docutils literal notranslate"><span class="pre">Tensor</span></code>) on a remote worker. This handle keeps the referenced remote
value alive on the owner, but there is no implication that the value will be
transferred to the local worker in the future. RRefs can be used in
multi-machine training by holding references to <a class="reference external" href="https://pytorch.org/docs/stable/nn.html#torch.nn.Module">nn.Modules</a> that exist on
other workers, and calling the appropriate functions to retrieve or modify their
parameters during training. See <a class="reference internal" href="rpc/rref.html#remote-reference-protocol"><span class="std std-ref">Remote Reference Protocol</span></a> for more
details.</p>
<dl class="py class">
<dt class="sig sig-object py" id="torch.distributed.rpc.RRef">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">torch.distributed.rpc.</span></span><span class="sig-name descname"><span class="pre">RRef</span></span><a class="reference internal" href="_modules/torch/distributed/rpc/api.html#RRef"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#torch.distributed.rpc.RRef" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<div class="toctree-wrapper compound">
<p class="caption" role="heading"><span class="caption-text">More Information about RRef</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="rpc/rref.html">Remote Reference Protocol</a><ul>
<li class="toctree-l2"><a class="reference internal" href="rpc/rref.html#background">Background</a></li>
<li class="toctree-l2"><a class="reference internal" href="rpc/rref.html#assumptions">Assumptions</a></li>
<li class="toctree-l2"><a class="reference internal" href="rpc/rref.html#rref-lifetime">RRef Lifetime</a><ul>
<li class="toctree-l3"><a class="reference internal" href="rpc/rref.html#design-reasoning">Design Reasoning</a></li>
<li class="toctree-l3"><a class="reference internal" href="rpc/rref.html#implementation">Implementation</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="rpc/rref.html#protocol-scenarios">Protocol Scenarios</a><ul>
<li class="toctree-l3"><a class="reference internal" href="rpc/rref.html#user-share-rref-with-owner-as-return-value">User Share RRef with Owner as Return Value</a></li>
<li class="toctree-l3"><a class="reference internal" href="rpc/rref.html#user-share-rref-with-owner-as-argument">User Share RRef with Owner as Argument</a></li>
<li class="toctree-l3"><a class="reference internal" href="rpc/rref.html#owner-share-rref-with-user">Owner Share RRef with User</a></li>
<li class="toctree-l3"><a class="reference internal" href="rpc/rref.html#user-share-rref-with-user">User Share RRef with User</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</section>
<section id="remotemodule">
<span id="remote-module"></span><h2>RemoteModule<a class="headerlink" href="#remotemodule" title="Permalink to this heading">¶</a></h2>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>RemoteModule is not currently supported when using CUDA tensors</p>
</div>
<p><code class="docutils literal notranslate"><span class="pre">RemoteModule</span></code> is an easy way to create an nn.Module remotely on a different
process. The actual module resides on a remote host, but the local host has a
handle to this module and invoke this module similar to a regular nn.Module.
The invocation however incurs RPC calls to the remote end and can be performed
asynchronously if needed via additional APIs supported by RemoteModule.</p>
<dl class="py class">
<dt class="sig sig-object py" id="torch.distributed.nn.api.remote_module.RemoteModule">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">torch.distributed.nn.api.remote_module.</span></span><span class="sig-name descname"><span class="pre">RemoteModule</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/torch/distributed/nn/api/remote_module.html#RemoteModule"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#torch.distributed.nn.api.remote_module.RemoteModule" title="Permalink to this definition">¶</a></dt>
<dd><blockquote>
<div><p>A RemoteModule instance can only be created after RPC initialization.
It creates a user-specified module on a specified remote node.
It behaves like a regular <code class="docutils literal notranslate"><span class="pre">nn.Module</span></code> except that the <code class="docutils literal notranslate"><span class="pre">forward</span></code> method is
executed on the remote node.
It takes care of autograd recording to ensure the backward pass propagates
gradients back to the corresponding remote module.</p>
<p>It generates two methods <code class="docutils literal notranslate"><span class="pre">forward_async</span></code> and <code class="docutils literal notranslate"><span class="pre">forward</span></code> based on the
signature of the <code class="docutils literal notranslate"><span class="pre">forward</span></code> method of <code class="docutils literal notranslate"><span class="pre">module_cls</span></code>. <code class="docutils literal notranslate"><span class="pre">forward_async</span></code>
runs asynchronously and returns a Future. The arguments of <code class="docutils literal notranslate"><span class="pre">forward_async</span></code>
and <code class="docutils literal notranslate"><span class="pre">forward</span></code> are the same as the <code class="docutils literal notranslate"><span class="pre">forward</span></code> method of the module
returned by the <code class="docutils literal notranslate"><span class="pre">module_cls</span></code>.</p>
<p>For example, if <code class="docutils literal notranslate"><span class="pre">module_cls</span></code> returns an instance of <code class="docutils literal notranslate"><span class="pre">nn.Linear</span></code>,
that has <code class="docutils literal notranslate"><span class="pre">forward</span></code> method signature: <code class="docutils literal notranslate"><span class="pre">def</span> <span class="pre">forward(input:</span> <span class="pre">Tensor)</span> <span class="pre">-&gt;</span> <span class="pre">Tensor:</span></code>,
the generated <code class="docutils literal notranslate"><span class="pre">RemoteModule</span></code> will have 2 methods with the signatures:</p>
<div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">def</span> <span class="pre">forward(input:</span> <span class="pre">Tensor)</span> <span class="pre">-&gt;</span> <span class="pre">Tensor:</span></code></div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">def</span> <span class="pre">forward_async(input:</span> <span class="pre">Tensor)</span> <span class="pre">-&gt;</span> <span class="pre">Future[Tensor]:</span></code></div>
</div>
</div></blockquote>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>remote_device</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.11)"><em>str</em></a>) – Device on the destination worker where we’d like to place this module.
The format should be “&lt;workername&gt;/&lt;device&gt;”, where the device field can be parsed as torch.device type.
E.g., “trainer0/cpu”, “trainer0”, “ps0/cuda:0”.
In addition, the device field can be optional and the default value is “cpu”.</p></li>
<li><p><strong>module_cls</strong> (<a class="reference internal" href="generated/torch.nn.Module.html#torch.nn.Module" title="torch.nn.Module"><em>nn.Module</em></a>) – <p>Class for the module to be created remotely. For example,</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">MyModule</span><span class="p">(</span><span class="n">nn</span><span class="o">.</span><span class="n">Module</span><span class="p">):</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="k">def</span> <span class="nf">forward</span><span class="p">(</span><span class="nb">input</span><span class="p">):</span>
<span class="gp">&gt;&gt;&gt; </span>        <span class="k">return</span> <span class="nb">input</span> <span class="o">+</span> <span class="mi">1</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">module_cls</span> <span class="o">=</span> <span class="n">MyModule</span>
</pre></div>
</div>
</p></li>
<li><p><strong>args</strong> (<em>Sequence</em><em>, </em><em>optional</em>) – args to be passed to <code class="docutils literal notranslate"><span class="pre">module_cls</span></code>.</p></li>
<li><p><strong>kwargs</strong> (<em>Dict</em><em>, </em><em>optional</em>) – kwargs to be passed to <code class="docutils literal notranslate"><span class="pre">module_cls</span></code>.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>A remote module instance which wraps the <code class="xref py py-class docutils literal notranslate"><span class="pre">Module</span></code> created by the
user-provided <code class="docutils literal notranslate"><span class="pre">module_cls</span></code>, it has a blocking <code class="docutils literal notranslate"><span class="pre">forward</span></code> method and an
asynchronous <code class="docutils literal notranslate"><span class="pre">forward_async</span></code> method that returns a future of the <code class="docutils literal notranslate"><span class="pre">forward</span></code> call
on the user-provided module on the remote side.</p>
</dd>
</dl>
<dl>
<dt>Example::</dt><dd><p>Run the following code in two different processes:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="c1"># On worker 0:</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">torch</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">torch.distributed.rpc</span> <span class="k">as</span> <span class="nn">rpc</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">torch</span> <span class="kn">import</span> <span class="n">nn</span><span class="p">,</span> <span class="n">Tensor</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">torch.distributed.nn.api.remote_module</span> <span class="kn">import</span> <span class="n">RemoteModule</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rpc</span><span class="o">.</span><span class="n">init_rpc</span><span class="p">(</span><span class="s2">&quot;worker0&quot;</span><span class="p">,</span> <span class="n">rank</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">world_size</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">remote_linear_module</span> <span class="o">=</span> <span class="n">RemoteModule</span><span class="p">(</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="s2">&quot;worker1/cpu&quot;</span><span class="p">,</span> <span class="n">nn</span><span class="o">.</span><span class="n">Linear</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="mi">20</span><span class="p">,</span> <span class="mi">30</span><span class="p">),</span>
<span class="gp">&gt;&gt;&gt; </span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">input</span> <span class="o">=</span> <span class="n">torch</span><span class="o">.</span><span class="n">randn</span><span class="p">(</span><span class="mi">128</span><span class="p">,</span> <span class="mi">20</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ret_fut</span> <span class="o">=</span> <span class="n">remote_linear_module</span><span class="o">.</span><span class="n">forward_async</span><span class="p">(</span><span class="nb">input</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ret</span> <span class="o">=</span> <span class="n">ret_fut</span><span class="o">.</span><span class="n">wait</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rpc</span><span class="o">.</span><span class="n">shutdown</span><span class="p">()</span>
</pre></div>
</div>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="c1"># On worker 1:</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">torch</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">torch.distributed.rpc</span> <span class="k">as</span> <span class="nn">rpc</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rpc</span><span class="o">.</span><span class="n">init_rpc</span><span class="p">(</span><span class="s2">&quot;worker1&quot;</span><span class="p">,</span> <span class="n">rank</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">world_size</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">rpc</span><span class="o">.</span><span class="n">shutdown</span><span class="p">()</span>
</pre></div>
</div>
<p>Furthermore, a more practical example that is combined with
<a class="reference external" href="https://pytorch.org/docs/stable/nn.html#torch.nn.parallel.DistributedDataParallel">DistributedDataParallel</a> (DDP)
can be found in this <a class="reference external" href="https://pytorch.org/tutorials/advanced/rpc_ddp_tutorial.html">tutorial</a>.</p>
</dd>
</dl>
<dl class="py method">
<dt class="sig sig-object py" id="torch.distributed.nn.api.remote_module.RemoteModule.get_module_rref">
<span class="sig-name descname"><span class="pre">get_module_rref</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#torch.distributed.nn.api.remote_module.RemoteModule.get_module_rref" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns an <a class="reference internal" href="#torch.distributed.rpc.RRef" title="torch.distributed.rpc.RRef"><code class="xref py py-class docutils literal notranslate"><span class="pre">RRef</span></code></a> (<code class="docutils literal notranslate"><span class="pre">RRef[nn.Module]</span></code>)
pointing to the remote module.</p>
<dl class="field-list simple">
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference internal" href="#torch.distributed.rpc.RRef" title="torch.distributed.rpc.api.RRef"><em>RRef</em></a>[<a class="reference internal" href="generated/torch.nn.Module.html#torch.nn.Module" title="torch.nn.modules.module.Module"><em>Module</em></a>]</p>
</dd>
</dl>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="torch.distributed.nn.api.remote_module.RemoteModule.remote_parameters">
<span class="sig-name descname"><span class="pre">remote_parameters</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">recurse</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#torch.distributed.nn.api.remote_module.RemoteModule.remote_parameters" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a list of <a class="reference internal" href="#torch.distributed.rpc.RRef" title="torch.distributed.rpc.RRef"><code class="xref py py-class docutils literal notranslate"><span class="pre">RRef</span></code></a> pointing to the
remote module’s parameters. This can typically be used in conjuction
with <a class="reference internal" href="distributed.optim.html#torch.distributed.optim.DistributedOptimizer" title="torch.distributed.optim.DistributedOptimizer"><code class="xref py py-class docutils literal notranslate"><span class="pre">DistributedOptimizer</span></code></a>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>recurse</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.11)"><em>bool</em></a>) – if True, then returns parameters of the remote
module and all submodules of the remote module. Otherwise,
returns only parameters that are direct members of the
remote module.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>A list of <a class="reference internal" href="#torch.distributed.rpc.RRef" title="torch.distributed.rpc.RRef"><code class="xref py py-class docutils literal notranslate"><span class="pre">RRef</span></code></a> (<code class="docutils literal notranslate"><span class="pre">List[RRef[nn.Parameter]]</span></code>)
to remote module’s parameters.</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.List" title="(in Python v3.11)"><em>List</em></a>[<a class="reference internal" href="#torch.distributed.rpc.RRef" title="torch.distributed.rpc.api.RRef"><em>RRef</em></a>[<a class="reference internal" href="generated/torch.nn.parameter.Parameter.html#torch.nn.parameter.Parameter" title="torch.nn.parameter.Parameter"><em>Parameter</em></a>]]</p>
</dd>
</dl>
</dd></dl>

</dd></dl>

</section>
<section id="distributed-autograd-framework">
<h2>Distributed Autograd Framework<a class="headerlink" href="#distributed-autograd-framework" title="Permalink to this heading">¶</a></h2>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Distributed autograd is not currently supported when using CUDA tensors</p>
</div>
<p>This module provides an RPC-based distributed autograd framework that can be
used for applications such as model parallel training. In short, applications
may send and receive gradient recording tensors over RPC. In the forward pass,
we record when gradient recording tensors are sent over RPC and during the
backward pass we use this information to perform a distributed backward pass
using RPC. For more details see <a class="reference internal" href="rpc/distributed_autograd.html#distributed-autograd-design"><span class="std std-ref">Distributed Autograd Design</span></a>.</p>
<span class="target" id="module-torch.distributed.autograd"></span><dl class="py function">
<dt class="sig sig-object py" id="torch.distributed.autograd.backward">
<span class="sig-prename descclassname"><span class="pre">torch.distributed.autograd.</span></span><span class="sig-name descname"><span class="pre">backward</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">context_id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.11)"><span class="pre">int</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">roots</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">List</span><span class="p"><span class="pre">[</span></span><a class="reference internal" href="tensors.html#torch.Tensor" title="torch.Tensor"><span class="pre">Tensor</span></a><span class="p"><span class="pre">]</span></span></span></em>, <em class="sig-param"><span class="n"><span class="pre">retain_graph</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.11)"><span class="pre">None</span></a></span></span><a class="headerlink" href="#torch.distributed.autograd.backward" title="Permalink to this definition">¶</a></dt>
<dd><p>Kicks off the distributed backward pass using the provided roots. This
currently implements the <a class="reference internal" href="rpc/distributed_autograd.html#fast-mode-algorithm"><span class="std std-ref">FAST mode algorithm</span></a> which
assumes all RPC messages sent in the same distributed autograd context
across workers would be part of the autograd graph during the backward pass.</p>
<p>We use the provided roots to discover the autograd graph and compute
appropriate dependencies. This method blocks until the entire
autograd computation is done.</p>
<p>We accumulate the gradients in the appropriate
<a class="reference internal" href="#torch.distributed.autograd.context" title="torch.distributed.autograd.context"><code class="xref py py-class docutils literal notranslate"><span class="pre">torch.distributed.autograd.context</span></code></a> on each of the nodes. The autograd
context to be used is looked up given the <code class="docutils literal notranslate"><span class="pre">context_id</span></code> that is passed in when
<a class="reference internal" href="#torch.distributed.autograd.backward" title="torch.distributed.autograd.backward"><code class="xref py py-meth docutils literal notranslate"><span class="pre">torch.distributed.autograd.backward()</span></code></a> is called. If there is no valid
autograd context corresponding to the given ID, we throw an error. You can
retrieve the accumulated gradients using the
<a class="reference internal" href="#torch.distributed.autograd.get_gradients" title="torch.distributed.autograd.get_gradients"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_gradients()</span></code></a> API.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>context_id</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.11)"><em>int</em></a>) – The autograd context id for which we should retrieve the gradients.</p></li>
<li><p><strong>roots</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#list" title="(in Python v3.11)"><em>list</em></a>) – Tensors which represent the roots of the autograd
computation. All the tensors should be scalars.</p></li>
<li><p><strong>retain_graph</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.11)"><em>bool</em></a><em>, </em><em>optional</em>) – If False, the graph used to compute the grad
will be freed. Note that in nearly all cases setting this
option to True is not needed and often can be worked around
in a much more efficient way. Usually, you need to set this
to True to run backward multiple times.</p></li>
</ul>
</dd>
</dl>
<dl>
<dt>Example::</dt><dd><div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">torch.distributed.autograd</span> <span class="k">as</span> <span class="nn">dist_autograd</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">dist_autograd</span><span class="o">.</span><span class="n">context</span><span class="p">()</span> <span class="k">as</span> <span class="n">context_id</span><span class="p">:</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">pred</span> <span class="o">=</span> <span class="n">model</span><span class="o">.</span><span class="n">forward</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">loss</span> <span class="o">=</span> <span class="n">loss_func</span><span class="p">(</span><span class="n">pred</span><span class="p">,</span> <span class="n">loss</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">dist_autograd</span><span class="o">.</span><span class="n">backward</span><span class="p">(</span><span class="n">context_id</span><span class="p">,</span> <span class="n">loss</span><span class="p">)</span>
</pre></div>
</div>
</dd>
</dl>
</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="torch.distributed.autograd.context">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">torch.distributed.autograd.</span></span><span class="sig-name descname"><span class="pre">context</span></span><a class="reference internal" href="_modules/torch/distributed/autograd.html#context"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#torch.distributed.autograd.context" title="Permalink to this definition">¶</a></dt>
<dd><p>Context object to wrap forward and backward passes when using
distributed autograd. The <code class="docutils literal notranslate"><span class="pre">context_id</span></code> generated in the <code class="docutils literal notranslate"><span class="pre">with</span></code>
statement  is required to uniquely identify a distributed backward pass
on all workers. Each worker stores metadata associated with this
<code class="docutils literal notranslate"><span class="pre">context_id</span></code>, which is required to correctly execute a distributed
autograd pass.</p>
<dl>
<dt>Example::</dt><dd><div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">torch.distributed.autograd</span> <span class="k">as</span> <span class="nn">dist_autograd</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">dist_autograd</span><span class="o">.</span><span class="n">context</span><span class="p">()</span> <span class="k">as</span> <span class="n">context_id</span><span class="p">:</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">t1</span> <span class="o">=</span> <span class="n">torch</span><span class="o">.</span><span class="n">rand</span><span class="p">((</span><span class="mi">3</span><span class="p">,</span> <span class="mi">3</span><span class="p">),</span> <span class="n">requires_grad</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">t2</span> <span class="o">=</span> <span class="n">torch</span><span class="o">.</span><span class="n">rand</span><span class="p">((</span><span class="mi">3</span><span class="p">,</span> <span class="mi">3</span><span class="p">),</span> <span class="n">requires_grad</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">loss</span> <span class="o">=</span> <span class="n">rpc</span><span class="o">.</span><span class="n">rpc_sync</span><span class="p">(</span><span class="s2">&quot;worker1&quot;</span><span class="p">,</span> <span class="n">torch</span><span class="o">.</span><span class="n">add</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">t1</span><span class="p">,</span> <span class="n">t2</span><span class="p">))</span><span class="o">.</span><span class="n">sum</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">dist_autograd</span><span class="o">.</span><span class="n">backward</span><span class="p">(</span><span class="n">context_id</span><span class="p">,</span> <span class="p">[</span><span class="n">loss</span><span class="p">])</span>
</pre></div>
</div>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="torch.distributed.autograd.get_gradients">
<span class="sig-prename descclassname"><span class="pre">torch.distributed.autograd.</span></span><span class="sig-name descname"><span class="pre">get_gradients</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">context_id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.11)"><span class="pre">int</span></a></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Dict</span><span class="p"><span class="pre">[</span></span><a class="reference internal" href="tensors.html#torch.Tensor" title="torch.Tensor"><span class="pre">Tensor</span></a><span class="p"><span class="pre">,</span></span><span class="w"> </span><a class="reference internal" href="tensors.html#torch.Tensor" title="torch.Tensor"><span class="pre">Tensor</span></a><span class="p"><span class="pre">]</span></span></span></span><a class="headerlink" href="#torch.distributed.autograd.get_gradients" title="Permalink to this definition">¶</a></dt>
<dd><p>Retrieves a map from Tensor to the appropriate gradient for that Tensor
accumulated in the provided context corresponding to the given <code class="docutils literal notranslate"><span class="pre">context_id</span></code>
as part of the distributed autograd backward pass.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>context_id</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.11)"><em>int</em></a>) – The autograd context id for which we should retrieve the
gradients.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>A map where the key is the Tensor and the value is the associated gradient
for that Tensor.</p>
</dd>
</dl>
<dl>
<dt>Example::</dt><dd><div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">torch.distributed.autograd</span> <span class="k">as</span> <span class="nn">dist_autograd</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">dist_autograd</span><span class="o">.</span><span class="n">context</span><span class="p">()</span> <span class="k">as</span> <span class="n">context_id</span><span class="p">:</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">t1</span> <span class="o">=</span> <span class="n">torch</span><span class="o">.</span><span class="n">rand</span><span class="p">((</span><span class="mi">3</span><span class="p">,</span> <span class="mi">3</span><span class="p">),</span> <span class="n">requires_grad</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">t2</span> <span class="o">=</span> <span class="n">torch</span><span class="o">.</span><span class="n">rand</span><span class="p">((</span><span class="mi">3</span><span class="p">,</span> <span class="mi">3</span><span class="p">),</span> <span class="n">requires_grad</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">loss</span> <span class="o">=</span> <span class="n">t1</span> <span class="o">+</span> <span class="n">t2</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">dist_autograd</span><span class="o">.</span><span class="n">backward</span><span class="p">(</span><span class="n">context_id</span><span class="p">,</span> <span class="p">[</span><span class="n">loss</span><span class="o">.</span><span class="n">sum</span><span class="p">()])</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">grads</span> <span class="o">=</span> <span class="n">dist_autograd</span><span class="o">.</span><span class="n">get_gradients</span><span class="p">(</span><span class="n">context_id</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="nb">print</span><span class="p">(</span><span class="n">grads</span><span class="p">[</span><span class="n">t1</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="nb">print</span><span class="p">(</span><span class="n">grads</span><span class="p">[</span><span class="n">t2</span><span class="p">])</span>
</pre></div>
</div>
</dd>
</dl>
</dd></dl>

<div class="toctree-wrapper compound">
<p class="caption" role="heading"><span class="caption-text">More Information about RPC Autograd</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="rpc/distributed_autograd.html">Distributed Autograd Design</a><ul>
<li class="toctree-l2"><a class="reference internal" href="rpc/distributed_autograd.html#background">Background</a></li>
<li class="toctree-l2"><a class="reference internal" href="rpc/distributed_autograd.html#autograd-recording-during-the-forward-pass">Autograd recording during the forward pass</a></li>
<li class="toctree-l2"><a class="reference internal" href="rpc/distributed_autograd.html#distributed-autograd-context">Distributed Autograd Context</a></li>
<li class="toctree-l2"><a class="reference internal" href="rpc/distributed_autograd.html#distributed-backward-pass">Distributed Backward Pass</a><ul>
<li class="toctree-l3"><a class="reference internal" href="rpc/distributed_autograd.html#computing-dependencies">Computing dependencies</a></li>
<li class="toctree-l3"><a class="reference internal" href="rpc/distributed_autograd.html#fast-mode-algorithm">FAST mode algorithm</a></li>
<li class="toctree-l3"><a class="reference internal" href="rpc/distributed_autograd.html#smart-mode-algorithm">SMART mode algorithm</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="rpc/distributed_autograd.html#distributed-optimizer">Distributed Optimizer</a></li>
<li class="toctree-l2"><a class="reference internal" href="rpc/distributed_autograd.html#simple-end-to-end-example">Simple end to end example</a></li>
</ul>
</li>
</ul>
</div>
</section>
<section id="distributed-optimizer">
<h2>Distributed Optimizer<a class="headerlink" href="#distributed-optimizer" title="Permalink to this heading">¶</a></h2>
<p>See the <a class="reference external" href="https://pytorch.org/docs/master/distributed.optim.html">torch.distributed.optim</a> page for documentation on distributed optimizers.</p>
</section>
<section id="design-notes">
<h2>Design Notes<a class="headerlink" href="#design-notes" title="Permalink to this heading">¶</a></h2>
<p>The distributed autograd design note covers the design of the RPC-based distributed autograd framework that is useful for applications such as model parallel training.</p>
<ul class="simple">
<li><p><a class="reference internal" href="rpc/distributed_autograd.html#distributed-autograd-design"><span class="std std-ref">Distributed Autograd Design</span></a></p></li>
</ul>
<p>The RRef design note covers the design of the <a class="reference internal" href="#rref"><span class="std std-ref">RRef</span></a> (Remote REFerence) protocol used to refer to values on remote workers by the framework.</p>
<ul class="simple">
<li><p><a class="reference internal" href="rpc/rref.html#remote-reference-protocol"><span class="std std-ref">Remote Reference Protocol</span></a></p></li>
</ul>
</section>
<section id="tutorials">
<h2>Tutorials<a class="headerlink" href="#tutorials" title="Permalink to this heading">¶</a></h2>
<p>The RPC tutorials introduce users to the RPC framework, provide several example applications
using <a class="reference internal" href="#distributed-rpc-framework"><span class="std std-ref">torch.distributed.rpc</span></a> APIs, and demonstrate how
to use <a class="reference external" href="https://pytorch.org/docs/stable/autograd.html#profiler">the profiler</a> to profile RPC-based workloads.</p>
<ul class="simple">
<li><p><a class="reference external" href="https://pytorch.org/tutorials/intermediate/rpc_tutorial.html">Getting started with Distributed RPC Framework</a></p></li>
<li><p><a class="reference external" href="https://pytorch.org/tutorials/intermediate/rpc_param_server_tutorial.html">Implementing a Parameter Server using Distributed RPC Framework</a></p></li>
<li><p><a class="reference external" href="https://pytorch.org/tutorials/advanced/rpc_ddp_tutorial.html">Combining Distributed DataParallel with Distributed RPC Framework</a> (covers <strong>RemoteModule</strong> as well)</p></li>
<li><p><a class="reference external" href="https://pytorch.org/tutorials/recipes/distributed_rpc_profiling.html">Profiling RPC-based Workloads</a></p></li>
<li><p><a class="reference external" href="https://pytorch.org/tutorials/intermediate/rpc_async_execution.html">Implementing batch RPC processing</a></p></li>
<li><p><a class="reference external" href="https://pytorch.org/tutorials/intermediate/dist_pipeline_parallel_tutorial.html">Distributed Pipeline Parallel</a></p></li>
</ul>
</section>
</section>


             </article>
             
            </div>
            <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <a href="rpc/rref.html" class="btn btn-neutral float-right" title="Remote Reference Protocol" accesskey="n" rel="next">Next <img src="_static/images/chevron-right-orange.svg" class="next-page"></a>
      
      
        <a href="torch.ao.ns._numeric_suite_fx.html" class="btn btn-neutral" title="torch.ao.ns._numeric_suite_fx" accesskey="p" rel="prev"><img src="_static/images/chevron-right-orange.svg" class="previous-page"> Previous</a>
      
    </div>
  

    <hr>

  
  <div role="contentinfo">
    <p>
        &copy; Copyright 2023, PyTorch Contributors.

    </p>
  </div>
    
      <div>
        Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
      </div>
     

</footer>

          </div>
<script>

var match = window.location.href.match(/\/_[a-zA-Z0-9_]*.html|_dynamo/gi);
var url = window.location.href.lastIndexOf(match[match.length-1]);

if (url)
  {
    var div = '<div class="admonition note"><p class="admonition-title">Note</p><p><i class="fa fa-exclamation-circle" aria-hidden="true">&nbsp</i> This page describes an internal API which is not intended to be used outside of the PyTorch codebase and can be modified or removed without notice.</p></div>'
    document.getElementById("pytorch-article").insertAdjacentHTML('afterBegin', div)
  }
</script>
        </div>

        <div class="pytorch-content-right" id="pytorch-content-right">
          <div class="pytorch-right-menu" id="pytorch-right-menu">
            <div class="pytorch-side-scroll" id="pytorch-side-scroll-right">
              <ul>
<li><a class="reference internal" href="#">Distributed RPC Framework</a><ul>
<li><a class="reference internal" href="#basics">Basics</a></li>
<li><a class="reference internal" href="#rpc">RPC</a><ul>
<li><a class="reference internal" href="#backends">Backends</a><ul>
<li><a class="reference internal" href="#tensorpipe-backend">TensorPipe Backend</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#rref">RRef</a></li>
<li><a class="reference internal" href="#remotemodule">RemoteModule</a></li>
<li><a class="reference internal" href="#distributed-autograd-framework">Distributed Autograd Framework</a></li>
<li><a class="reference internal" href="#distributed-optimizer">Distributed Optimizer</a></li>
<li><a class="reference internal" href="#design-notes">Design Notes</a></li>
<li><a class="reference internal" href="#tutorials">Tutorials</a></li>
</ul>
</li>
</ul>

            </div>
          </div>
        </div>
      </section>
    </div>

  
       <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
         <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
         <script src="_static/jquery.js"></script>
         <script src="_static/underscore.js"></script>
         <script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
         <script src="_static/doctools.js"></script>
         <script src="_static/clipboard.min.js"></script>
         <script src="_static/copybutton.js"></script>
     

  <script type="text/javascript" src="_static/js/vendor/popper.min.js"></script>
  <script type="text/javascript" src="_static/js/vendor/bootstrap.min.js"></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/list.js/1.5.0/list.min.js"></script>
  <script type="text/javascript" src="_static/js/theme.js"></script>

  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script>
 
<script script type="text/javascript">
  var collapsedSections = ['Developer Notes', 'Language Bindings', 'Libraries', 'Community'];
</script>

<img height="1" width="1" style="border-style:none;" alt="" src="https://www.googleadservices.com/pagead/conversion/795629140/?label=txkmCPmdtosBENSssfsC&amp;guid=ON&amp;script=0"/>


  <!-- Begin Footer -->

  <div class="container-fluid docs-tutorials-resources" id="docs-tutorials-resources">
    <div class="container">
      <div class="row">
        <div class="col-md-4 text-center">
          <h2>Docs</h2>
          <p>Access comprehensive developer documentation for PyTorch</p>
          <a class="with-right-arrow" href="https://pytorch.org/docs/stable/index.html">View Docs</a>
        </div>

        <div class="col-md-4 text-center">
          <h2>Tutorials</h2>
          <p>Get in-depth tutorials for beginners and advanced developers</p>
          <a class="with-right-arrow" href="https://pytorch.org/tutorials">View Tutorials</a>
        </div>

        <div class="col-md-4 text-center">
          <h2>Resources</h2>
          <p>Find development resources and get your questions answered</p>
          <a class="with-right-arrow" href="https://pytorch.org/resources">View Resources</a>
        </div>
      </div>
    </div>
  </div>

  <footer class="site-footer">
    <div class="container footer-container">
      <div class="footer-logo-wrapper">
        <a href="https://pytorch.org/" class="footer-logo"></a>
      </div>

      <div class="footer-links-wrapper">
        <div class="footer-links-col">
          <ul>
            <li class="list-title"><a href="https://pytorch.org/">PyTorch</a></li>
            <li><a href="https://pytorch.org/get-started">Get Started</a></li>
            <li><a href="https://pytorch.org/features">Features</a></li>
            <li><a href="https://pytorch.org/ecosystem">Ecosystem</a></li>
            <li><a href="https://pytorch.org/blog/">Blog</a></li>
            <li><a href="https://github.com/pytorch/pytorch/blob/master/CONTRIBUTING.md">Contributing</a></li>
          </ul>
        </div>

        <div class="footer-links-col">
          <ul>
            <li class="list-title"><a href="https://pytorch.org/resources">Resources</a></li>
            <li><a href="https://pytorch.org/tutorials">Tutorials</a></li>
            <li><a href="https://pytorch.org/docs/stable/index.html">Docs</a></li>
            <li><a href="https://discuss.pytorch.org" target="_blank">Discuss</a></li>
            <li><a href="https://github.com/pytorch/pytorch/issues" target="_blank">Github Issues</a></li>
            <li><a href="https://pytorch.org/assets/brand-guidelines/PyTorch-Brand-Guidelines.pdf" target="_blank">Brand Guidelines</a></li>
          </ul>
        </div>

        <div class="footer-links-col">
          <ul>
            <li class="list-title">Stay up to date</li>
            <li><a href="https://www.facebook.com/pytorch" target="_blank">Facebook</a></li>
            <li><a href="https://twitter.com/pytorch" target="_blank">Twitter</a></li>
            <li><a href="https://www.youtube.com/pytorch" target="_blank">YouTube</a></li>
            <li><a href="https://www.linkedin.com/company/pytorch" target="_blank">LinkedIn</a></li>
          </ul>  
          </div>

        <div class="footer-links-col">
          <ul>
            <li class="list-title">PyTorch Podcasts</li>
            <li><a href="https://open.spotify.com/show/6UzHKeiy368jKfQMKKvJY5" target="_blank">Spotify</a></li>
            <li><a href="https://podcasts.apple.com/us/podcast/pytorch-developer-podcast/id1566080008" target="_blank">Apple</a></li>
            <li><a href="https://www.google.com/podcasts?feed=aHR0cHM6Ly9mZWVkcy5zaW1wbGVjYXN0LmNvbS9PQjVGa0lsOA%3D%3D" target="_blank">Google</a></li>
            <li><a href="https://music.amazon.com/podcasts/7a4e6f0e-26c2-49e9-a478-41bd244197d0/PyTorch-Developer-Podcast?" target="_blank">Amazon</a></li>
          </ul>
         </div>
        </div>
        
        <div class="privacy-policy">
          <ul>
            <li class="privacy-policy-links"><a href="https://www.linuxfoundation.org/terms/" target="_blank">Terms</a></li>
            <li class="privacy-policy-links">|</li>
            <li class="privacy-policy-links"><a href="https://www.linuxfoundation.org/privacy-policy/" target="_blank">Privacy</a></li>
          </ul>
        </div>
        <div class="copyright">
        <p>© Copyright The Linux Foundation. The PyTorch Foundation is a project of The Linux Foundation.
          For web site terms of use, trademark policy and other policies applicable to The PyTorch Foundation please see
          <a href="www.linuxfoundation.org/policies/">www.linuxfoundation.org/policies/</a>. The PyTorch Foundation supports the PyTorch open source
          project, which has been established as PyTorch Project a Series of LF Projects, LLC. For policies applicable to the PyTorch Project a Series of LF Projects, LLC,
          please see <a href="www.lfprojects.org/policies/">www.lfprojects.org/policies/</a>.</p>
      </div>
     </div>

  </footer>

  <div class="cookie-banner-wrapper">
  <div class="container">
    <p class="gdpr-notice">To analyze traffic and optimize your experience, we serve cookies on this site. By clicking or navigating, you agree to allow our usage of cookies. As the current maintainers of this site, Facebook’s Cookies Policy applies. Learn more, including about available controls: <a href="https://www.facebook.com/policies/cookies/">Cookies Policy</a>.</p>
    <img class="close-button" src="_static/images/pytorch-x.svg">
  </div>
</div>

  <!-- End Footer -->

  <!-- Begin Mobile Menu -->

  <div class="mobile-main-menu">
    <div class="container-fluid">
      <div class="container">
        <div class="mobile-main-menu-header-container">
          <a class="header-logo" href="https://pytorch.org/" aria-label="PyTorch"></a>
          <a class="main-menu-close-button" href="#" data-behavior="close-mobile-menu"></a>
        </div>
      </div>
    </div>

    <div class="mobile-main-menu-links-container">
      <div class="main-menu">
        <ul>
          <li>
            <a href="https://pytorch.org/get-started">Get Started</a>
          </li>

          <li>
            <a href="https://pytorch.org/ecosystem">Ecosystem</a>
          </li>
            
          <li>
            <a href="https://pytorch.org/mobile">Mobile</a>
          </li>

          <li>
            <a href="https://pytorch.org/blog/">Blog</a>
          </li>

          <li>
            <a href="https://pytorch.org/tutorials">Tutorials</a>
          </li>

          <li class="resources-mobile-menu-title" class="active">
            Docs
          </li>

          <ul class="resources-mobile-menu-items">
            <li>
              <a href="https://pytorch.org/docs/stable/index.html">PyTorch</a>
            </li>

            <li>
              <a href="https://pytorch.org/audio/stable/index.html">torchaudio</a>
            </li>

            <li>
              <a href="https://pytorch.org/text/stable/index.html">torchtext</a>
            </li>

            <li>
              <a href="https://pytorch.org/vision/stable/index.html">torchvision</a>
            </li>

            <li>
              <a href="https://pytorch.org/torcharrow">torcharrow</a>
            </li>

            <li>
              <a href="https://pytorch.org/data">TorchData</a>
            </li>

            <li>
              <a href="https://pytorch.org/torchrec">TorchRec</a>
            </li>

            <li>
              <a href="https://pytorch.org/serve/">TorchServe</a>
            </li>

            <li>
              <a href="https://pytorch.org/torchx/">TorchX</a>
            </li>

            <li>
              <a href="https://pytorch.org/xla">PyTorch on XLA Devices</a>
            </li>
          </ul>

          <li class="resources-mobile-menu-title">
            Resources
          </li>
            
           <ul class="resources-mobile-menu-items">

            <li>
              <a href="https://pytorch.org/features">About</a>
            </li>

            <li>
              <a href="https://pytorch.org/foundation">PyTorch Foundation</a>
            </li>

            <li>
              <a href="https://pytorch.org/#community-module">Community</a>
            </li>

            <li>
              <a href="https://pytorch.org/community-stories">Community Stories</a>
            </li>

            <li>
              <a href="https://pytorch.org/resources">Developer Resources</a>
            </li>

            <li>
              <a href="https://pytorch.org/events">Events</a>
            </li>

            <li>
              <a href="https://discuss.pytorch.org/">Forums</a>
            </li>

            <li>
              <a href="https://pytorch.org/hub">Models (Beta)</a>
            </li>
          </ul>

          <li>
            <a href="https://github.com/pytorch/pytorch">Github</a>
          </li>
        </ul>
      </div>
    </div>
  </div>

  <!-- End Mobile Menu -->

  <script type="text/javascript" src="_static/js/vendor/anchor.min.js"></script>

  <script type="text/javascript">
    $(document).ready(function() {
      mobileMenu.bind();
      mobileTOC.bind();
      pytorchAnchors.bind();
      sideMenus.bind();
      scrollToAnchor.bind();
      highlightNavigation.bind();
      mainMenuDropdown.bind();
      filterTags.bind();

      // Add class to links that have code blocks, since we cannot create links in code blocks
      $("article.pytorch-article a span.pre").each(function(e) {
        $(this).closest("a").addClass("has-code");
      });
    })
  </script>
</body>
</html>