1 /*- 2 * Copyright (c) 2009, 2020 Oracle and/or its affiliates. All rights reserved. 3 * 4 * See the file LICENSE for license information. 5 * 6 */ 7 using System; 8 using System.Collections.Generic; 9 using System.Text; 10 11 namespace BerkeleyDB { 12 /// <summary> 13 /// A class representing configuration parameters for a 14 /// <see cref="DatabaseEnvironment"/>'s replication subsystem. 15 /// </summary> 16 public class ReplicationConfig { 17 18 /// <summary> 19 /// Instantiate a new ReplicationConfig object with default 20 /// configuration values. 21 /// </summary> ReplicationConfig()22 public ReplicationConfig() { 23 AutoInit = true; 24 Elections = true; 25 RepmgrSitesConfig = new List<DbSiteConfig>(); 26 } 27 28 #region Config Flags 29 /// <summary> 30 /// If true, the replication master sends groups of records to the 31 /// clients in a single network transfer 32 /// </summary> 33 public bool BulkTransfer; 34 /// <summary> 35 /// If true, the client delays synchronizing to a newly declared 36 /// master (defaults to false). Clients configured in this way 37 /// remain unsynchronized until the application calls 38 /// <see cref="DatabaseEnvironment.RepSync"/>. 39 /// </summary> 40 public bool DelayClientSync; 41 /// <summary> 42 /// If true, replication only stores the internal information in-memory 43 /// and cannot keep persistent state across a site crash or reboot. By 44 /// default, it is false and replication creates files in the 45 /// environment home directory to preserve the internal information. 46 /// This configuration flag can only be set before the 47 /// <see cref="DatabaseEnvironment"/> is opened. 48 /// </summary> 49 public bool InMemory; 50 /// <summary> 51 /// If true, master leases are used for this site (defaults to 52 /// false). 53 /// </summary> 54 /// <remarks> 55 /// Configuring this option may result in a 56 /// <see cref="LeaseExpiredException"/> when attempting to read entries 57 /// from a database after the site's master lease has expired. 58 /// </remarks> 59 public bool UseMasterLeases; 60 /// <summary> 61 /// If true, the replication master automatically re-initializes 62 /// outdated clients (defaults to true). 63 /// </summary> 64 public bool AutoInit; 65 /// <summary> 66 /// If true, Berkeley DB method calls that would normally block while 67 /// clients are in recovery will return errors immediately (defaults to 68 /// false). 69 /// </summary> 70 public bool NoBlocking; 71 /// <summary> 72 /// If true, the Replication Manager observes the strict "majority" 73 /// rule in managing elections, even in a group with only 2 sites. This 74 /// means the client in a 2-site group is unable to take over as 75 /// master if the original master fails or becomes disconnected. (See 76 /// the Elections section in the Berkeley DB Reference Guide for more 77 /// information.) Both sites in the replication group should have the 78 /// same value for this parameter. 79 /// </summary> 80 public bool Strict2Site; 81 /// <summary> 82 /// If true, then prevents the use of poll() for polling network events 83 /// </summary> 84 public bool DisablePoll; 85 /// <summary> 86 /// If true, then prevents the use of SSL for securing messages shared 87 /// between nodes of a replication group. 88 /// </summary> 89 public bool DisableSSL; 90 /// <summary> 91 /// If true, Replication Manager automatically runs elections to 92 /// choose a new master when the old master appears to 93 /// have become disconnected (defaults to true). 94 /// </summary> 95 public bool Elections; 96 /// <summary> 97 /// If true, then forces the use of Epoll for polling of network events 98 /// </summary> 99 public bool EnableEpoll; 100 /// <summary> 101 /// This flag is used to specify the preferred master site in a 102 /// replication group operating in preferred master mode. A preferred 103 /// master replication group must contain only two sites, with one site 104 /// specified as the preferred master site and the other site specified 105 /// as the client site. The preferred master site operates as the 106 /// master site whenever possible. 107 /// </summary> 108 public bool PrefmasMaster; 109 /// <summary> 110 /// This flag is used to specify the client site in a replication group 111 /// operating in preferred master mode. A preferred master replication 112 /// group must contain only two sites, with one site specified as the 113 /// preferred master site and the other site specified as the client 114 /// site. The client site in a preferred master replication group takes 115 /// over temporarily as master when the preferred master site is 116 /// unavailable. 117 /// </summary> 118 public bool PrefmasClient; 119 /// <summary> 120 /// Enable simple write forwarding for this site. By default, write 121 /// operations cannot be performed on a replication client site. This 122 /// option enables forwarding of simple client put and delete operations 123 /// to the master site for processing. These operations must use an implicit 124 /// NULL transaction ID to be forwarded. Any other write operation that 125 /// specifies a non-NULL transaction throws a DatabaseException. The master 126 /// must have an open database handle for the database on which a forwarded 127 /// write operation is being performed. All sites in the replication group 128 /// should have the same value for this configuration option. 129 /// </summary> 130 public bool ForwardWrites; 131 #endregion Config Flags 132 133 #region Timeout Values 134 private uint _ackTimeout; 135 internal bool ackTimeoutIsSet; 136 /// <summary> 137 /// The amount of time the replication manager's transport function 138 /// waits to collect enough acknowledgments from replication group 139 /// clients, before giving up and returning a failure indication. The 140 /// default wait time is 1 second. 141 /// </summary> 142 public uint AckTimeout { 143 get { return _ackTimeout; } 144 set { 145 _ackTimeout = value; 146 ackTimeoutIsSet = true; 147 } 148 } 149 150 private uint _checkpointDelay; 151 internal bool checkpointDelayIsSet; 152 /// <summary> 153 /// The amount of time a master site delays between completing a 154 /// checkpoint and writing a checkpoint record into the log. 155 /// </summary> 156 /// <remarks> 157 /// This delay allows clients to complete their own checkpoints before 158 /// the master requires completion of them. The default is 30 seconds. 159 /// If all databases in the environment, and the environment's 160 /// transaction log, are configured to reside in-memory (never preserved 161 /// to disk), then, although checkpoints are still necessary, the delay 162 /// is not useful and should be set to 0. 163 /// </remarks> 164 public uint CheckpointDelay { 165 get { return _checkpointDelay; } 166 set { 167 _checkpointDelay = value; 168 checkpointDelayIsSet = true; 169 } 170 } 171 172 private uint _connectionRetry; 173 internal bool connectionRetryIsSet; 174 /// <summary> 175 /// The amount of time the replication manager waits before trying 176 /// to re-establish a connection to another site after a communication 177 /// failure. The default wait time is 30 seconds. 178 /// </summary> 179 public uint ConnectionRetry { 180 get { return _connectionRetry; } 181 set { 182 _connectionRetry = value; 183 connectionRetryIsSet = true; 184 } 185 } 186 187 private uint _electionTimeout; 188 internal bool electionTimeoutIsSet; 189 /// <summary> 190 /// The timeout period for an election. The default timeout is 2 191 /// seconds. 192 /// </summary> 193 public uint ElectionTimeout { 194 get { return _electionTimeout; } 195 set { 196 _electionTimeout = value; 197 electionTimeoutIsSet = true; 198 } 199 } 200 201 private uint _electionRetry; 202 internal bool electionRetryIsSet; 203 /// <summary> 204 /// Configure the amount of time the replication manager waits 205 /// before retrying a failed election. The default wait time is 10 206 /// seconds. 207 /// </summary> 208 public uint ElectionRetry { 209 get { return _electionRetry; } 210 set { 211 _electionRetry = value; 212 electionRetryIsSet = true; 213 } 214 } 215 216 private uint _fullElectionTimeout; 217 internal bool fullElectionTimeoutIsSet; 218 /// <summary> 219 /// An optional configuration timeout period to wait for full election 220 /// participation the first time the replication group finds a master. 221 /// By default this option is turned off and normal election timeouts 222 /// are used. (See the Elections section in the Berkeley DB Reference 223 /// Guide for more information.) 224 /// </summary> 225 public uint FullElectionTimeout { 226 get { return _fullElectionTimeout; } 227 set { 228 _fullElectionTimeout = value; 229 fullElectionTimeoutIsSet = true; 230 } 231 } 232 233 private uint _heartbeatMonitor; 234 internal bool heartbeatMonitorIsSet; 235 /// <summary> 236 /// The amount of time the replication manager, running at a client 237 /// site, waits for some message activity on the connection from the 238 /// master (heartbeats or other messages) before concluding that the 239 /// connection has been lost. When 0 (the default), no monitoring is 240 /// performed. 241 /// </summary> 242 public uint HeartbeatMonitor { 243 get { return _heartbeatMonitor; } 244 set { 245 _heartbeatMonitor = value; 246 heartbeatMonitorIsSet = true; 247 } 248 } 249 250 private uint _heartbeatSend; 251 internal bool heartbeatSendIsSet; 252 /// <summary> 253 /// The frequency at which the replication manager, running at a master 254 /// site, broadcasts a heartbeat message in an otherwise idle system. 255 /// When 0 (the default), no heartbeat messages are sent. 256 /// </summary> 257 public uint HeartbeatSend { 258 get { return _heartbeatSend; } 259 set { 260 _heartbeatSend = value; 261 heartbeatSendIsSet = true; 262 } 263 } 264 265 private uint _leaseTimeout; 266 internal bool leaseTimeoutIsSet; 267 /// <summary> 268 /// The amount of time a client grants its master lease to a master. 269 /// When using master leases all sites in a replication group must use 270 /// the same lease timeout value. There is no default value. If leases 271 /// are desired, this method must be called prior to calling 272 /// <see cref="DatabaseEnvironment.RepStartClient"/> or 273 /// <see cref="DatabaseEnvironment.RepStartMaster"/>. 274 /// </summary> 275 public uint LeaseTimeout { 276 get { return _leaseTimeout; } 277 set { 278 _leaseTimeout = value; 279 leaseTimeoutIsSet = true; 280 } 281 } 282 283 private uint _writeForwardTimeout; 284 internal bool writeForwardTimeoutIsSet; 285 /// <summary> 286 /// Configure the amount of time a Replication Manager client waits 287 /// for a response from a forwarded write operation before returning 288 /// a failure indication. The default value is 5 seconds. 289 /// </summary> 290 public uint WriteForwardTimeout { 291 get { return _writeForwardTimeout; } 292 set { 293 _writeForwardTimeout = value; 294 writeForwardTimeoutIsSet = true; 295 } 296 } 297 #endregion Timeout Values 298 299 private uint _clockskewFast; 300 private uint _clockskewSlow; 301 internal bool clockskewIsSet; 302 /// <summary> 303 /// The value, relative to <see cref="ClockskewSlow"/>, of the fastest 304 /// clock in the group of sites. 305 /// </summary> 306 public uint ClockskewFast { get { return _clockskewFast; } } 307 /// <summary> 308 /// The value of the slowest clock in the group of sites. 309 /// </summary> 310 public uint ClockskewSlow { get { return _clockskewSlow; } } 311 /// <summary> 312 /// Set the clock skew ratio among replication group members based on 313 /// the fastest and slowest measurements among the group for use with 314 /// master leases. 315 /// </summary> 316 /// <remarks> 317 /// <para> 318 /// Calling this method is optional, the default values for clock skew 319 /// assume no skew. The user must also configure leases via 320 /// <see cref="UseMasterLeases"/>. Additionally, the user must also 321 /// set the master lease timeout via <see cref="LeaseTimeout"/> and 322 /// the number of sites in the replication group via 323 /// <see cref="NSites"/>. These settings may be configured in any 324 /// order. For a description of the clock skew values, see Clock skew 325 /// in the Berkeley DB Programmer's Reference Guide. For a description 326 /// of master leases, see Master leases in the Berkeley DB Programmer's 327 /// Reference Guide. 328 /// </para> 329 /// <para> 330 /// These arguments can be used to express either raw measurements of a 331 /// clock timing experiment or a percentage across machines. For 332 /// instance a group of sites have a 2% variance, then 333 /// <paramref name="fast"/> should be set to 102, and 334 /// <paramref name="slow"/> should be set to 100. Or, for a 0.03% 335 /// difference, you can use 10003 and 10000 respectively. 336 /// </para> 337 /// </remarks> 338 /// <param name="fast"> 339 /// The value, relative to <paramref name="slow"/>, of the fastest clock 340 /// in the group of sites. 341 /// </param> 342 /// <param name="slow"> 343 /// The value of the slowest clock in the group of sites. 344 /// </param> Clockskew(uint fast, uint slow)345 public void Clockskew(uint fast, uint slow) { 346 clockskewIsSet = true; 347 _clockskewSlow = slow; 348 _clockskewFast = fast; 349 } 350 351 private uint _nsites; 352 internal bool nsitesIsSet; 353 /// <summary> 354 /// The total number of sites in the replication group. 355 /// </summary> 356 /// <remarks> 357 /// <para> 358 /// This setting is typically used by applications which use the 359 /// Berkeley DB library "replication manager" support. (However, see 360 /// also <see cref="DatabaseEnvironment.RepHoldElection"/>, the 361 /// description of the nsites parameter.) 362 /// </para> 363 /// </remarks> 364 public uint NSites { 365 get { return _nsites; } 366 set { 367 _nsites = value; 368 nsitesIsSet = true; 369 } 370 } 371 private uint _priority; 372 internal bool priorityIsSet; 373 /// <summary> 374 /// The database environment's priority in replication group elections. 375 /// A special value of 0 indicates that this environment cannot be a 376 /// replication group master. If not configured, then a default value 377 /// of 100 is used. 378 /// </summary> 379 public uint Priority { 380 get { return _priority; } 381 set { 382 _priority = value; 383 priorityIsSet = true; 384 } 385 } 386 387 private ReplicationViewDelegate replicationView; 388 internal bool repViewIsSet; 389 /// <summary> 390 /// Create a replication view and specify the function to determine 391 /// whether a database file is replicated to the local site. 392 /// </summary> 393 /// <remarks> 394 /// If it is null, the replication view is a full view and all database 395 /// files are replicated to the local site. Otherwise it is a partial 396 /// view and only some database files are replicated to the local site. 397 /// </remarks> 398 public ReplicationViewDelegate ReplicationView { 399 get { return replicationView; } 400 set { 401 repViewIsSet = true; 402 replicationView = value; 403 } 404 } 405 406 private uint _retransmissionRequestMin; 407 private uint _retransmissionRequestMax; 408 internal bool retransmissionRequestIsSet; 409 /// <summary> 410 /// The minimum number of microseconds a client waits before requesting 411 /// retransmission. 412 /// </summary> 413 public uint RetransmissionRequestMin { 414 get { return _retransmissionRequestMin; } 415 } 416 /// <summary> 417 /// The maximum number of microseconds a client waits before requesting 418 /// retransmission. 419 /// </summary> 420 public uint RetransmissionRequestMax { 421 get { return _retransmissionRequestMax; } 422 } 423 /// <summary> 424 /// Set a threshold for the minimum and maximum time that a client waits 425 /// before requesting retransmission of a missing message. 426 /// </summary> 427 /// <remarks> 428 /// <para> 429 /// If the client detects a gap in the sequence of incoming log records 430 /// or database pages, Berkeley DB waits for at least 431 /// <paramref name="min"/> microseconds before requesting retransmission 432 /// of the missing record. Berkeley DB doubles that amount before 433 /// requesting the same missing record again, and so on, up to a 434 /// maximum threshold of <paramref name="max"/> microseconds. 435 /// </para> 436 /// <para> 437 /// These values are thresholds only. Replication Manager applications 438 /// use these values to determine when to automatically request 439 /// retransmission of missing messages. For Base API applications, 440 /// Berkeley DB has no thread available in the library as a timer, the 441 /// threshold is only checked when a thread enters the Berkeley DB 442 /// library to process an incoming replication message. Any amount of 443 /// time may have passed since the last message arrived and Berkeley DB 444 /// only checks whether the amount of time since a request was made is 445 /// beyond the threshold value or not. 446 /// </para> 447 /// <para> 448 /// By default the minimum is 40000 and the maximum is 1280000 (1.28 449 /// seconds). These defaults are fairly arbitrary and the application 450 /// likely needs to adjust these. The values should be based on expected 451 /// load and performance characteristics of the master and client host 452 /// platforms and transport infrastructure as well as round-trip message 453 /// time. 454 /// </para></remarks> 455 /// <param name="min"> 456 /// The minimum number of microseconds a client waits before requesting 457 /// retransmission. 458 /// </param> 459 /// <param name="max"> 460 /// The maximum number of microseconds a client waits before requesting 461 /// retransmission. 462 /// </param> RetransmissionRequest(uint min, uint max)463 public void RetransmissionRequest(uint min, uint max) { 464 retransmissionRequestIsSet = true; 465 _retransmissionRequestMin = min; 466 _retransmissionRequestMax = max; 467 } 468 469 private uint _gbytes; 470 private uint _bytes; 471 internal bool transmitLimitIsSet; 472 /// <summary> 473 /// The gigabytes component of the byte-count limit on the amount of 474 /// data that is transmitted from a site in response to a single 475 /// message processed by 476 /// <see cref="DatabaseEnvironment.RepProcessMessage"/>. 477 /// </summary> 478 public uint TransmitLimitGBytes { get { return _gbytes; } } 479 /// <summary> 480 /// The bytes component of the byte-count limit on the amount of data 481 /// that is transmitted from a site in response to a single 482 /// message processed by 483 /// <see cref="DatabaseEnvironment.RepProcessMessage"/>. 484 /// </summary> 485 public uint TransmitLimitBytes { get { return _bytes; } } 486 /// <summary> 487 /// Set a byte-count limit on the amount of data that is 488 /// transmitted from a site in response to a single message processed by 489 /// <see cref="DatabaseEnvironment.RepProcessMessage"/>. The limit is 490 /// not a hard limit, and the record that exceeds the limit is the last 491 /// record to be sent. 492 /// </summary> 493 /// <remarks> 494 /// <para> 495 /// Record transmission throttling is turned on by default with a limit 496 /// of 10MB. 497 /// </para> 498 /// <para> 499 /// If both <paramref name="GBytes"/> and <paramref name="Bytes"/> are 500 /// zero, then the transmission limit is turned off. 501 /// </para> 502 /// </remarks> 503 /// <param name="GBytes"> 504 /// The number of gigabytes which, when added to 505 /// <paramref name="Bytes"/>, specifies the maximum number of bytes that 506 /// are sent in a single call to 507 /// <see cref="DatabaseEnvironment.RepProcessMessage"/>. 508 /// </param> 509 /// <param name="Bytes"> 510 /// The number of bytes which, when added to 511 /// <paramref name="GBytes"/>, specifies the maximum number of bytes 512 /// that are sent in a single call to 513 /// <see cref="DatabaseEnvironment.RepProcessMessage"/>. 514 /// </param> TransmitLimit(uint GBytes, uint Bytes)515 public void TransmitLimit(uint GBytes, uint Bytes) { 516 transmitLimitIsSet = true; 517 _gbytes = GBytes; 518 _bytes = Bytes; 519 } 520 521 private uint _inqmaxgbytes; 522 private uint _inqmaxbytes; 523 internal bool repmgrIncomingQueueMaxIsSet; 524 /// <summary> 525 /// The gigabytes component of the maximum amount of dynamic memory 526 /// used by the Replication Manager incoming queue. 527 /// </summary> 528 public uint RepmgrIncomingQueueMaxGBytes { get { return _inqmaxgbytes; } } 529 /// <summary> 530 /// The bytes component of the maximum amount of dynamic memory 531 /// used by the Replication Manager incoming queue. 532 /// </summary> 533 public uint RepmgrIncomingQueueMaxBytes { get { return _inqmaxbytes; } } 534 /// <summary> 535 /// Set a byte-count limit on the maximum amount of dynamic memory 536 /// used by the Replication Manager incoming queue. 537 /// </summary> 538 /// <remarks> 539 /// <para> 540 /// By default, the Replication Manager incoming queue size has a 541 /// limit of 100MB. 542 /// </para> 543 /// <para> 544 /// If both <paramref name="GBytes"/> and <paramref name="Bytes"/> are 545 /// zero, then the Replication Manager incoming queue size is limited 546 /// by available heap memory. 547 /// </para> 548 /// </remarks> 549 /// <param name="GBytes"> 550 /// The number of gigabytes which, when added to 551 /// <paramref name="Bytes"/>, specifies the maximum amount of dynamic 552 /// memory used by the Replication Manager incoming queue. 553 /// </param> 554 /// <param name="Bytes"> 555 /// The number of bytes which, when added to 556 /// <paramref name="GBytes"/>, specifies the maximum amount of dynamic 557 /// memory used by the Replication Manager incoming queue. 558 /// </param> RepmgrIncomingQueueMax(uint GBytes, uint Bytes)559 public void RepmgrIncomingQueueMax(uint GBytes, uint Bytes) { 560 repmgrIncomingQueueMaxIsSet = true; 561 _inqmaxgbytes = GBytes; 562 _inqmaxbytes = Bytes; 563 } 564 565 /// <summary> 566 /// The delegate used to transmit data using the replication 567 /// application's communication infrastructure. 568 /// </summary> 569 public ReplicationTransportDelegate Transport; 570 571 /// <summary> 572 /// Specify how master and client sites handle the acknowledgment of 573 /// replication messages which is necessary for "permanent" records. 574 /// The current implementation requires all sites in a replication group 575 /// to configure the same acknowledgement policy. 576 /// </summary> 577 /// <seealso cref="AckTimeout"/> 578 public AckPolicy RepMgrAckPolicy; 579 580 /// <summary> 581 /// A list of site configurations. 582 /// </summary> 583 public List<DbSiteConfig> RepmgrSitesConfig; 584 } 585 } 586