1	<?php
2	declare( strict_types = 1 );
3
4	/**
5	* Interface for salvageable services.
6	*
7	* @license GPL-2.0-or-later
8	* @file
9	*/
10
11	namespace Wikimedia\Services;
12
13	/**
14	* SalvageableService defines an interface for services that are able to salvage state from a
15	* previous instance of the same class. The intent is to allow new service instances to re-use
16	* resources that would be expensive to re-create, such as cached data or network connections.
17	*
18	* @note There is no expectation that services will be destroyed when the process (or web request)
19	* terminates.
20	*/
21	interface SalvageableService {
22
23	/**
24	* Re-uses state from $other. $other must not be used after being passed to salvage(),
25	* and should be considered to be destroyed.
26	*
27	* @note Implementations are responsible for determining what parts of $other can be re-used
28	* safely. In particular, implementations should check that the relevant configuration of
29	* $other is the same as in $this before re-using resources from $other.
30	*
31	* @note Implementations must take care to detach any re-used resources from the original
32	* service instance. If $other is destroyed later, resources that are now used by the
33	* new service instance must not be affected.
34	*
35	* @note If $other is a DestructibleService, implementations should make sure that $other
36	* is in destroyed state after salvage finished. This may be done by calling $other->destroy()
37	* after carefully detaching all relevant resources.
38	*
39	* @param SalvageableService $other The object to salvage state from. $other must have the
40	* exact same type as $this.
41	*/
42	public function salvage( SalvageableService $other );
43
44	}