1	<?php
2	/**
3	* This program is free software; you can redistribute it and/or modify
4	* it under the terms of the GNU General Public License as published by
5	* the Free Software Foundation; either version 2 of the License, or
6	* (at your option) any later version.
7	*
8	* This program is distributed in the hope that it will be useful,
9	* but WITHOUT ANY WARRANTY; without even the implied warranty of
10	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11	* GNU General Public License for more details.
12	*
13	* You should have received a copy of the GNU General Public License along
14	* with this program; if not, write to the Free Software Foundation, Inc.,
15	* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16	* http://www.gnu.org/copyleft/gpl.html
17	*
18	* @file
19	*/
20	namespace Wikimedia\Rdbms;
21
22	/**
23	* Internal interface between a database object and load balancer.
24	*
25	* @ingroup Database
26	* @internal
27	*/
28	interface IDatabaseForOwner extends IDatabase {
29
30	/**
31	* Run a callback after each time any transaction commits or rolls back
32	*
33	* The callback takes two arguments:
34	*   - IDatabase::TRIGGER_COMMIT or IDatabase::TRIGGER_ROLLBACK
35	*   - This IDatabase object
36	* Callbacks must commit any transactions that they begin.
37	*
38	* Registering a callback here will not affect writesOrCallbacks() pending.
39	*
40	* Since callbacks from this or onTransactionCommitOrIdle() can start and end transactions,
41	* a single call to IDatabase::commit might trigger multiple runs of the listener callbacks.
42	*
43	* @param string $name Callback name
44	* @param callable|null $callback Use null to unset a listener
45	* @since 1.28
46	*/
47	public function setTransactionListener( $name, callable $callback = null );
48
49	/**
50	* @return bool Whether this DB server is running in server-side read-only mode
51	* @throws DBError If an error occurs, {@see query}
52	* @since 1.28
53	*/
54	public function serverIsReadOnly();
55
56	/**
57	* Get the replication position of this primary DB server
58	*
59	* @return DBPrimaryPos|false Position; false if this is not a primary DB
60	* @throws DBError If an error occurs, {@see query}
61	* @since 1.37
62	*/
63	public function getPrimaryPos();
64
65	/**
66	* Get the time spend running write queries for this transaction
67	*
68	* High values could be due to scanning, updates, locking, and such.
69	*
70	* @param string $type IDatabase::ESTIMATE_* constant [default: ESTIMATE_ALL]
71	* @return float|false Returns false if not transaction is active
72	* @since 1.26
73	*/
74	public function pendingWriteQueryDuration( $type = self::ESTIMATE_TOTAL );
75
76	/**
77	* Whether there is a transaction open with either possible write queries
78	* or unresolved pre-commit/commit/resolution callbacks pending
79	*
80	* This does *not* count recurring callbacks, e.g. from setTransactionListener().
81	*
82	* @return bool
83	*/
84	public function writesOrCallbacksPending();
85
86	/**
87	* @return bool Whether there is a transaction open with possible write queries
88	* @since 1.27
89	*/
90	public function writesPending();
91
92	/**
93	* Get the list of method names that did write queries for this transaction
94	*
95	* @return array
96	* @since 1.27
97	*/
98	public function pendingWriteCallers();
99
100	/**
101	* Release important session-level state (named lock, table locks) as post-rollback cleanup
102	*
103	* This should only be called by a load balancer or if the handle is not attached to one.
104	* Also, there must be no chance that a future caller will still be expecting some of the
105	* lost session state.
106	*
107	* Connection and query errors will be suppressed and logged
108	*
109	* @param string $fname Calling function name
110	* @param string $flush Flush flag, set to a situationally valid IDatabase::FLUSHING_*
111	*   constant to disable warnings about explicitly rolling back implicit transactions.
112	*   This will silently break any ongoing explicit transaction. Only set the flush flag
113	*   if you are sure that it is safe to ignore these warnings in your context.
114	* @throws DBError If an error occurs, {@see query}
115	* @since 1.38
116	*/
117	public function flushSession( $fname = __METHOD__, $flush = self::FLUSHING_ONE );
118
119	/**
120	* Get the last time the connection may have been used for a write query
121	*
122	* @return int|float|false UNIX timestamp or false
123	* @since 1.24
124	*/
125	public function lastDoneWrites();
126
127	/**
128	* Set the entire array or a particular key of the managing load balancer info array
129	*
130	* Keys matching the IDatabase::LB_* constants are also used internally by subclasses
131	*
132	* @internal should not be called outside of rdbms library.
133	*
134	* @param array|string $nameOrArray The new array or the name of a key to set
135	* @param array|mixed|null $value If $nameOrArray is a string, the new key value (null to unset)
136	*/
137	public function setLBInfo( $nameOrArray, $value = null );
138
139	/**
140	* Wait for the replica server to catch up to a given primary server position
141	*
142	* Note that this does not start any new transactions.
143	*
144	* Callers might want to flush any existing transaction before invoking this method.
145	* Upon success, this assures that replica server queries will reflect all changes up
146	* to the given position, without interference from prior REPEATABLE-READ snapshots.
147	*
148	* @param DBPrimaryPos $pos
149	* @param int $timeout The maximum number of seconds to wait for synchronisation
150	* @return int|null Zero if the replica DB server was past that position already,
151	*   greater than zero if we waited for some period of time, less than
152	*   zero if it timed out, and null on error
153	* @throws DBError If an error occurs, {@see query}
154	* @since 1.37
155	*/
156	public function primaryPosWait( DBPrimaryPos $pos, $timeout );
157	}