includes/services/SalvageableService.php

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