includes/libs/services/SalvageableService.php

   1 <?php
   2
   3 namespace Wikimedia\Services;
   4
   5 /**
   6  * Interface for salvageable services.
   7  *
   8  * This program is free software; you can redistribute it and/or modify
   9  * it under the terms of the GNU General Public License as published by
  10  * the Free Software Foundation; either version 2 of the License, or
  11  * (at your option) any later version.
  12  *
  13  * This program is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  16  * GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License along
  19  * with this program; if not, write to the Free Software Foundation, Inc.,
  20  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  21  * http://www.gnu.org/copyleft/gpl.html
  22  *
  23  * @file
  24  *
  25  * @since 1.28
  26  */
  27
  28 /**
  29  * SalvageableService defines an interface for services that are able to salvage state from a
  30  * previous instance of the same class. The intent is to allow new service instances to re-use
  31  * resources that would be expensive to re-create, such as cached data or network connections.
  32  *
  33  * @note There is no expectation that services will be destroyed when the process (or web request)
  34  * terminates.
  35  */
  36 interface SalvageableService {
  37
  38         /**
  39          * Re-uses state from $other. $other must not be used after being passed to salvage(),
  40          * and should be considered to be destroyed.
  41          *
  42          * @note Implementations are responsible for determining what parts of $other can be re-used
  43          * safely. In particular, implementations should check that the relevant configuration of
  44          * $other is the same as in $this before re-using resources from $other.
  45          *
  46          * @note Implementations must take care to detach any re-used resources from the original
  47          * service instance. If $other is destroyed later, resources that are now used by the
  48          * new service instance must not be affected.
  49          *
  50          * @note If $other is a DestructibleService, implementations should make sure that $other
  51          * is in destroyed state after salvage finished. This may be done by calling $other->destroy()
  52          * after carefully detaching all relevant resources.
  53          *
  54          * @param SalvageableService $other The object to salvage state from. $other must have the
  55          * exact same type as $this.
  56          */
  57         public function salvage( SalvageableService $other );
  58
  59 }
  60
  61 /**
  62  * Retain the old class name for backwards compatibility.
  63  * @deprecated since 1.33
  64  */
  65 class_alias( SalvageableService::class, 'MediaWiki\Services\SalvageableService' );