From f198873b8f45d09612b252547e3884ea486baaa0 Mon Sep 17 00:00:00 2001 From: Guide Date: Sat, 25 Feb 2023 17:58:48 +0800 Subject: [PATCH] =?UTF-8?q?[docs=20update]=E5=AE=8C=E5=96=84=E5=88=86?= =?UTF-8?q?=E5=B8=83=E5=BC=8F=E9=94=81=EF=BC=88=E6=B7=BB=E5=8A=A0=20zookee?= =?UTF-8?q?per=E5=AE=9E=E7=8E=B0=E5=88=86=E5=B8=83=E5=BC=8F=E9=94=81?= =?UTF-8?q?=E7=9A=84=E6=96=B9=E5=BC=8F=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/distributed-system/distributed-lock.md | 169 +++++++++++++++++- .../distributed-lock-zookeeper.png | Bin 0 -> 18026 bytes 2 files changed, 167 insertions(+), 2 deletions(-) create mode 100644 docs/distributed-system/images/distributed-lock/distributed-lock-zookeeper.png diff --git a/docs/distributed-system/distributed-lock.md b/docs/distributed-system/distributed-lock.md index 9f3b4f78..90c784f9 100644 --- a/docs/distributed-system/distributed-lock.md +++ b/docs/distributed-system/distributed-lock.md @@ -6,7 +6,7 @@ icon: "lock" 网上有很多分布式锁相关的文章，写了一个相对简洁易懂的版本，针对面试和工作应该够用了。 -## 什么是分布式锁？ +## 分布式锁介绍 对于单机多线程来说，在 Java 中，我们通常使用 `ReetrantLock` 类、`synchronized` 关键字这类 JDK 自带的 **本地锁** 来控制一个 JVM 进程内的多个线程对本地共享资源的访问。 @@ -231,4 +231,169 @@ Redlock 实现比较复杂，性能比较差，发生时钟变迁的情况下还 实际项目中不建议使用 Redlock 算法，成本和收益不成正比。 -如果不是非要实现绝对可靠的分布式锁的话，其实单机版 Redis 就完全够了，实现简单，性能也非常高。如果你必须要实现一个绝对可靠的分布式锁的话，可以基于 Zookeeper 来做，只是性能会差一些。 +如果不是非要实现绝对可靠的分布式锁的话，其实单机版 Redis 就完全够了，实现简单，性能也非常高。如果你必须要实现一个绝对可靠的分布式锁的话，可以基于 ZooKeeper 来做，只是性能会差一些。 + +## 基于 ZooKeeper 实现分布式锁 + +Redis 实现分布式锁性能较高，ZooKeeper 实现分布式锁可靠性更高。实际项目中，我们应该根据业务的具体需求来选择。 + +### 如何基于 ZooKeeper 实现分布式锁？ + +ZooKeeper 分布式锁是基于 **临时顺序节点** 和 **Watcher（事件监听器）** 实现的。 + +获取锁： + +1. 首先我们要有一个持久节点`/locks`，客户端获取锁就是在`locks`下创建临时顺序节点。 +2. 假设客户端 1 创建了`/locks/lock1`节点，创建成功之后，会判断 `lock1`是否是 `/locks` 下最小的子节点。 +3. 如果 `lock1`是最小的子节点，则获取锁成功。否则，获取锁失败。 +4. 如果获取锁失败，则说明有其他的客户端已经成功获取锁。客户端 1 并不会不停地循环去尝试加锁，而是在前一个节点比如`/locks/lock0`上注册一个事件监听器。这个监听器的作用是当前一个节点释放锁之后通知客户端 1（避免无效自旋），这样客户端 1 就加锁成功了。 + +释放锁： + +1. 成功获取锁的客户端在执行完业务流程之后，会将对应的子节点删除。 +2. 成功获取锁的客户端在出现故障之后，对应的子节点由于是临时顺序节点，也会被自动删除，避免了锁无法被释放。 +3. 我们前面说的事件监听器其实监听的就是这个子节点删除事件，子节点删除就意味着锁被释放。 + +![](./images/distributed-lock/distributed-lock-zookeeper.png) + +实际项目中，推荐使用 Curator 来实现 ZooKeeper 分布式锁。Curator 是 Netflix 公司开源的一套 ZooKeeper Java 客户端框架，相比于 ZooKeeper 自带的客户端 zookeeper 来说，Curator 的封装更加完善，各种 API 都可以比较方便地使用。 + +`Curator`主要实现了下面四种锁： + +- `InterProcessMutex`：分布式可重入排它锁 +- `InterProcessSemaphoreMutex`：分布式不可重入排它锁 +- `InterProcessReadWriteLock`：分布式读写锁 +- `InterProcessMultiLock`：将多个锁作为单个实体管理的容器，获取锁的时候获取所有锁，释放锁也会释放所有锁资源（忽略释放失败的锁）。 + +```java +CuratorFramework client = ZKUtils.getClient(); +client.start(); +// 分布式可重入排它锁 +InterProcessLock lock1 = new InterProcessMutex(client, lockPath1); +// 分布式不可重入排它锁 +InterProcessLock lock2 = new InterProcessSemaphoreMutex(client, lockPath2); +// 锁 +InterProcessMultiLock lock = new InterProcessMultiLock(Arrays.asList(lock1, lock2)); + +if (!lock.acquire(10, TimeUnit.SECONDS)) { + throw new IllegalStateException("不能获取多锁"); +} +System.out.println("已获取多锁"); +System.out.println("是否有第一个锁: " + lock1.isAcquiredInThisProcess()); +System.out.println("是否有第二个锁: " + lock2.isAcquiredInThisProcess()); +try { + // 资源操作 + resource.use(); +} finally { + System.out.println("释放多个锁"); + lock.release(); +} +System.out.println("是否有第一个锁: " + lock1.isAcquiredInThisProcess()); +System.out.println("是否有第二个锁: " + lock2.isAcquiredInThisProcess()); +client.close(); +``` + +### 为什么要用临时顺序节点？ + +每个数据节点在 ZooKeeper 中被称为 **znode**，它是 ZooKeeper 中数据的最小单元。 + +我们通常是将 znode 分为 4 大类： + +- **持久（PERSISTENT）节点** ：一旦创建就一直存在即使 ZooKeeper 集群宕机，直到将其删除。 +- **临时（EPHEMERAL）节点** ：临时节点的生命周期是与 **客户端会话（session）** 绑定的，**会话消失则节点消失** 。并且，**临时节点只能做叶子节点** ，不能创建子节点。 +- **持久顺序（PERSISTENT_SEQUENTIAL）节点** ：除了具有持久（PERSISTENT）节点的特性之外， 子节点的名称还具有顺序性。比如 `/node1/app0000000001` 、`/node1/app0000000002` 。 +- **临时顺序（EPHEMERAL_SEQUENTIAL）节点** ：除了具备临时（EPHEMERAL）节点的特性之外，子节点的名称还具有顺序性。 + +可以看出，临时节点相比持久节点，最主要的是对会话失效的情况处理不一样，临时节点会话消失则对应的节点消失。这样的话，如果客户端发生异常导致没来得及释放锁也没关系，会话失效节点自动被删除，不会发生死锁的问题。 + +使用 Redis 实现分布式锁的时候，我们是通过过期时间来避免锁无法被释放导致死锁问题的，而 ZooKeeper 直接利用临时节点的特性即可。 + +假设不适用顺序节点的话，所有尝试获取锁的客户端都会对持有锁的子节点加监听器。当该锁被释放之后，势必会造成所有尝试获取锁的客户端来争夺锁，这样对性能不友好。使用顺序节点之后，只需要监听前一个节点就好了，对性能更友好。 + +### 为什么要设置对前一个节点的监听？ + +> Watcher（事件监听器），是 ZooKeeper 中的一个很重要的特性。ZooKeeper 允许用户在指定节点上注册一些 Watcher，并且在一些特定事件触发的时候，ZooKeeper 服务端会将事件通知到感兴趣的客户端上去，该机制是 ZooKeeper 实现分布式协调服务的重要特性。 + +同一时间段内，可能会有很多客户端同时获取锁，但只有一个可以获取成功。如果获取锁失败，则说明有其他的客户端已经成功获取锁。获取锁失败的客户端并不会不停地循环去尝试加锁，而是在前一个节点注册一个事件监听器。 + +这个事件监听器的作用是： **当前一个节点对应的客户端释放锁之后（也就是前一个节点被删除之后，监听的是删除事件），通知获取锁失败的客户端（唤醒等待的线程，Java 中的 `wait/notifyAll` ），让它尝试去获取锁，然后就成功获取锁了。** + +### 如何实现可重入锁？ + +这里以 Curator 的 `InterProcessMutex` 对可重入锁的实现来介绍（源码地址：[InterProcessMutex.java](https://github.com/apache/curator/blob/master/curator-recipes/src/main/java/org/apache/curator/framework/recipes/locks/InterProcessMutex.java)）。 + +当我们调用 `InterProcessMutex#acquire`方法获取锁的时候，会调用`InterProcessMutex#internalLock`方法。 + +```java +// 获取可重入互斥锁，直到获取成功为止 +@Override +public void acquire() throws Exception { + if (!internalLock(-1, null)) { + throw new IOException("Lost connection while trying to acquire lock: " + basePath); + } +} +``` + +`internalLock` 方法会先获取当前请求锁的线程，然后从 `threadData`( `ConcurrentMap` 类型)中获取当前线程对应的 `lockData` 。 `lockData` 包含锁的信息和加锁的次数，是实现可重入锁的关键。 + +第一次获取锁的时候，`lockData`为 `null`。获取锁成功之后，会将当前线程和对应的 `lockData` 放到 `threadData` 中 + +```java +private boolean internalLock(long time, TimeUnit unit) throws Exception { + // 获取当前请求锁的线程 + Thread currentThread = Thread.currentThread(); + // 拿对应的 lockData + LockData lockData = threadData.get(currentThread); + // 第一次获取锁的话，lockData 为 null + if (lockData != null) { + // 当前线程获取过一次锁之后 + // 因为当前线程的锁存在， lockCount 自增后返回，实现锁重入. + lockData.lockCount.incrementAndGet(); + return true; + } + // 尝试获取锁 + String lockPath = internals.attemptLock(time, unit, getLockNodeBytes()); + if (lockPath != null) { + LockData newLockData = new LockData(currentThread, lockPath); + // 获取锁成功之后，将当前线程和对应的 lockData 放到 threadData 中 + threadData.put(currentThread, newLockData); + return true; + } + + return false; +} +``` + +`LockData`是 `InterProcessMutex`中的一个静态内部类。 + +```java + +private final ConcurrentMap threadData = Maps.newConcurrentMap(); + +private static class LockData +{ + // 当前持有锁的线程 + final Thread owningThread; + // 锁对应的子节点 + final String lockPath; + // 加锁的次数 + final AtomicInteger lockCount = new AtomicInteger(1); + + private LockData(Thread owningThread, String lockPath) + { + this.owningThread = owningThread; + this.lockPath = lockPath; + } +} +``` + +如果已经获取过一次锁，后面再来获取锁的话，直接就会在 `if (lockData != null)` 这里被拦下了，然后就会执行`lockData.lockCount.incrementAndGet();` 将加锁次数加 1。 + +整个可重入锁的实现逻辑非常简单，直接在客户端判断当前线程有没有获取锁，有的话直接将加锁次数加 1 就可以了。 + +## 总结 + +这篇文章我们介绍了分布式锁的基本概念以及实现分布式锁的两种常见方式。至于具体选择 Redis 还是 ZooKeeper 来实现分布式锁，还是要看业务的具体需求。如果对性能要求比较高的话，建议使用 Redis 实现分布式锁。如果对可靠性要求比较高的话，建议使用 ZooKeeper 实现分布式锁。 + + + diff --git a/docs/distributed-system/images/distributed-lock/distributed-lock-zookeeper.png b/docs/distributed-system/images/distributed-lock/distributed-lock-zookeeper.png new file mode 100644 index 0000000000000000000000000000000000000000..dafa068d157ef07a0517f6c208a8708f2be5c1bc GIT binary patch literal 18026 zcmb@tS5#Bq7d09{K}9;!yNDD45fr2ts(>`XbfWcrC>T1e*Fc=94 zgAqTuMsjI+@Q)k192`H_G*CH(&Y=d9t>a_pXs}yFWp)F934n#gA7D>UFbfyqu-e*M z++6U*To437sA%HrS4iN(MEhkV$AnYBlnCiTycEpap{$I~BT*G6q9TXw9PQq`N&YR6 zxUC)az2W=v<|;BB*f`kg8}2vd;xgjk*cklrt?sV>X!_yf_ck@ww^>1!5rav@tFw)Vs~s10Bp*J5SeTWaf#Czci<+L~`s z*U&K3RsQ5me0;JxFgyqgh;+6y2D=13`T03GIq67A56%wRZ`?SmCIQPyX0k|BR8<3n zgx>J-O57nzOiPBzDZvCq9*FX9eI@CNA^tm7m0wg4lNb+k@UpRclO`eY9zlGU4R(e* zsV`4-^YoyiqB4{ts&1?c348Y`!C&mbgJcI{+(InumFd% zu!K0(eY z3d3E6(Xk)iM@7NJrKaugpM0V8(kB|88YT3~Vz+DhQ2F>NyQfS{F#VS=4OL;R>}T6u zFg5M>A|e|f*kQDEBY*c7rs}X8#hH&DLDeJ|GhV;OSF#FgHIr@nbl^FXk`tB^^S=DU z-#8Al>FQ8p*(pK$L!Ma$(oMgni>o`DIy*N$vdyiZF+_#AX6h{#lI29HZ$F_^g29x; z)Rh$s-p=m)6VvX3QNt9r1~_xW~ARrU}DR*iVi5G^oHv*C-qiINU4h(i`;_i12T1!!W};+QK@ z$lgW+Oujjopw#gHee|dO(fb5A{=PH0SE@0@ybZV6odSO0bpBMy>j#}6tHI=lOpr1& zDEL9vgIxWzPvZzIk-F{~xq)suQOQg+&4$ z5n;Q?Oa;(@;?f=;tQ~x=6w?LuZ6cYl1IT;(1nqe|&20dieCPkK2fEu25il3atIm&| zIV;H#JO8R3{~EEiA9CK3eHmQvlv({ZMUCvIQnl_HT`FxcmOZx7gvQNran-NVye<{$ zZVXxSR)I_((r<=`(A9h?R8N;rzw$tGNUxV#`UJj_)QY-m_#0bg-u%m00~^#XowHZI z>!_~dI}(EdsE!)Oh(-(Yao)Y{$}&kdaFgUeH>Wy@ET=;H*1KQziD2pqXS?ioO< z95=@@-S*}Oy4LX9+b^&IS)7KWMaJ=X!vZQj#yP)#PrrZWvn%ua`!uCP7N9$^TCFUy z>yHdadBTF*yMoS&w3_|^;_$ly)>TDOSTa z*x$(ys%nz*0AGb~7lW;(>qun3s(Kqo2}@zTx&M;hFC#{l#z_C?Am6y?_mWkjCYXEa zo{QQjQI!+z&Jdi{a$`cqa`Gsd+K5hd7*%5n{@6AgLC5BJOro;lhx3J|X?S}u_inay zcBlfy_CMt6IyyP*{_smGf9-FjvC;tri|Xb(N4vUf%0;M%Cwp`;XDJ^rg1G=+G)%hf zCUaEyBVpDJ#fsRXv_r1tl8aTed>?5>bF9&i{CJku!WpNc0L*k1l8R6-CJDPtVF=JK zX&ho%+3z2pYyLsTZ%ij~G&q2Pu6$wGx_!3KK0DsgeIk(oM7?2C`qA-=`it|uqn>-v zt`i^|awgC-^$9Cdme9F(96cB^8sC zjOr#ApMM`TD_$6&U@0>BBiD~kR1Fjw;jBq~PZ~kVa$Mus*zWKSQ>hKg{T;5QlxN8+ z;cLr%#CltD>o(^D!JE_b2Ox6_{p zaC-ZOl#rD3NkRQ9I)^iD9Ng|-cXMUo=(I@i&3ktK#}{!!8Df?`Lg+J2d1$aPft3q#(YrJxQ4&abe;7%78XbrhOdRRdQXU>#(PPp99+YAjdSvS>9blNp-;-_hEWf&=^Z{=FIQr-uo}%BS^4aC z?M&;4N<8y2{xR@N3K&L;4I?qO<+RulbG@hc=0&HW7Vp%wvWC=p+p_)~!(r%o+}t3C z6UVldtsE52yxI0AGm#;sQ@^^1elLpo<@i$dAKmYJo?zEIFEx2q2`}ydyDp$38CQL{ z3YT-w=PkN*bo9VaNW?s?LeSd9K?2GNAJFlY0xS!fh3Z4QL2j(fpOEFK+r7;AaPaIG z69%o9(t|Nh88k|RCc6z5Gd>xn#M&y#2Kbmdm7{4zr`N5)ZNSI?;x{QK-1AS;f4^C)(fasoF;x?PxU#Y`(O3BM z$KSNif2k)VQ;g{>Q!&MOEkl)Q61vNV*nA_~kAgGZ{2F*mH=J$(kCs{PM`Y4lTG`mF zrX`f@r$em%!LOe(duWtTc&OZS11*aG*u4&U`RU#32@H(uMx+jyeC3%|YqLx>lGWQz z(X&l;>c5~dQOvRei^WfW zr9-!%M> zsw8~$!%L*79$#T6ubx(Q>enD+ry;rjd1oMOj=E=Ibk53Op>1k|J2PQSY;%H+j3$5v z*Y02ygN2)#;H)&V>FA78cmUlb?0%Fa`ol~QIXU^+U54Ir4{iRH*iXxs^*#{L(s(L_ zp`th#bqXgr?y9OsfUDiXG}2YEK~-bKb{6DbIQy;J*huU>F6qVx9uy}YX&nr>6cnig z3rSh5*s7?oK*RKEVi4~4Y*NyX`wvZC7Wzh=lv%2Bug|ZclF-~QZl$LrOG78ez6iXB zEB0qSMu%fQ@IVV?-hpS2F?jZ8=*U;sxq!}6b97!5^58(hnva*qNsCvX+7a_T*h$3G zO&&3K_;0*SyJh9x6Pi}BX#tnH1v6r`8USpA9G^v9ke4~8-`zOe)n`8YP%|B#(X$lK z`q|BpMv)u%P?EeZ`jl|~^Pg%ZXN#v$3J}Gl7owYniZBW}Vhb7dT#_olGGfl13$)$K z7B=}a=Khe(DkTE9N8nnaOh?}y-%_Khw~WjNhGK*v3bEG48Xwb_tu-EgTWRI~<};3m zM+mxpL$O*hIf2}f=OD)NAuHowsc<|wUHV?@+ka(>phM~0pPwA0CVLx?k{&=FE2u$K z_8%Qpo!rrjjV$euH{vqYu8i1iKTxa``#wbayD6<&@FUXEaVZGLYzmgiNW>sM8Gm_r z_;kk6(Z%M&5vtlvI|JFGfE|gh-%0Bj?5iYbNiv=92jkYtMqHi*5?1g>Bk&KeCy?+R zj=2j5D+}lKYpD3!1AR3G57C?Bb29tEFgXNyEaB2 z*h`ljfuy;?!+%Gva#G1oUG@BsT59ArULVlyl5^T{eQSy0h`^$*suYCT_34Jzg_@7r zX-p1aB4IQqYU#zWZsQJRWUzor3`yH*W&R-t!Pb-21WdN{IUYwu*$M^3f&If*{UBgd z0yENj;q3Pczq~w+>YA}){h5tO3}tsyOg7@~PS`<0!E_h(D+_If4lGjiej05*!_4QL zDIPeKwNf!+ZY`z`>z6 z=y@$!Ca)$fx6>lQ7pr|v8FBK87MvEop=r>_V0F389sbTMmU7F1tRjxsUB z!rKn!{0{71snHEkl?D!yClJG5uojA+-Hjt;ZLI-;%Oi-IC(S|+F!61nrQ_1GsKHwg zHjJ<%tjl8MihT+`BKdnApW%#jo}=p=)Mu_|2;0yt%?SD zYX?)Fi(8b7#ATw24YGY}@P)%QT+^}^xXa$=dya1YL1)dYJ4kIsY_i2WqPgsrVOK0TSkUJ)w!yPK8l!C0*MGw#6 zWhBGUIaUMND++^IrT)S~L-T}YDT-h2Y|s;>CtO}`4gCE4KI5OGuHA?XTVNw;h?0u3 z5`G7Sgi@-Qu{8-$u0|~LzsOuoT9l5~7B)BQSEyWemulR~`S>~g%PvM1J2v9j&-ON1 zRwsA8&jUL^=K}lEX$5Mm0WPqRNSJ=U7<31d&S+?1s}%L&BUUsE zp_N6bg8CL61|b006TjtF4)4Yr4__5OsZ_h58l^1|bFqxf)5g>%vTLrlp*Nrp zn9CgD1pK?YcyJRVnTtAqY>L}9dip`FME9o+ScGvUwtM!fG4(qS?wh%L21JZy3_M0} zi3Q{Io2M;w!}Ax06^bRN6YEPx>``d%j*Ktfy?*H%_%~mKq(vTNq(DS# z8#2&_aR$WmbP(YQ`hFv%35x@6>EE$@=uq^{wH5o9f`ikS|$)C}B%G5_=c-3xBePB9hnc z2@CdGf%kN{gOOiPe08%p5Id9$oa^v^9e*>dY9Uh3HKa8XyFG*$CU*T9kuO;J9=}bp zE(LI+*=^%4;^LKhX1ePTawTYHgR|^b)u1&fxwZMaE>Fy|RPIfX{{!6oogGL2HzjWR ziRW6PPSiiBUxYq?L;F?vePm2c^sXK~GX;4KV}72U4OOk;n+_3$F{;mu7$&Dky~y$RRzS_m&^0cx#rUg`84!q@~c4gw6~l#oD-O#IQ9z}MggG1%1g zi_|<)t|wjibw_55>jOx(3bl9zC?;{Js`FE#@~mLl6ySRL~kS`)PWvbU=_cP`Z47eP0O!WQE- zhlVv9NiM>mvw&+8r#IFv7rMq57Z>&BbH=K~KB=F3Q| zIHWzW2<`9VWOD53pvg*bE9*bo_8Hc9`!&3>%Xz7ixcV{z66^aCHG3%5qD)Vh7{y(#S8e>lK(ty~IEns+RYS&agN*-|Vbe8=iFmzY6~R3*PfVd` zJ8ISSCTJab z?{%rPu3oHa=ey(Ov@XsPgZ`W0)=V7G`2EW|VJ_>G37KdLnwZBHl$M&>xq^Po%8%KJ z9t4PYwW=#P3@)NxS=TaYu79|Gbk1n0oREQ<2mrPN_Ln~ao>+YgPn&H1*qbxEQ)Zw> zBF{6UcOCsK3S)%~I~jr*dA#p7NAOy-q%@?LEUQb_&hqRCU~7QOCuwMlL+8S6L@z|u z7*#I{2MFWu93`PoYEw~qU5b3A`}oSVuF*ah56STG@DobF{Eh~-{f!J|gHrxN_WOPB z`|$s8gl~IW@W9lRxD|9m-zEd;--{=G+Z-a#UZq#}y_)?<^EZ*yMV-8ifG3$fJkgyM zEZ2+Z%^akGv;{m&|`|!l@`x=U-JyYqB5;Zpq;`T%8wH zpHzIqhb=8kQ>X0YvegHKZ|D~5?+tfEAhAfM1cv9$z)3?<8vTes0@aw_or22H4E;g9 zpS(8&X2`nR15hyv4be&{m{MkInQV71F0Dbo^K}Bzr8*m z4#vf#-Fa{%Iq{h18GTa9BrV^JNmK$0y~*1C$=B2ih=89*`+%&E)aOEtsd7YIW;ZLO zx%}ij&*P7ekN<8z_OP&(TQ`Ts+eN%+fQdhvL>@K0!b_Ca9<^J)ZG4k)Z}@)Pi7w}b zHqPcaQ0ViyUCLdM5Q~PdjSzNM_NPe9WP)(Veo~XHhk!l&NuxUMdzifB;kq~oJ}ayG z+v6<(kxy5Nf4HkUJVV~M3`{w8FQV8Pd5_J)j0scRf8_AHSE{~``9DFUyuV$k8vlaDVeOk@7KBjJ>x(d&jUugq@h%A_)QAQ+%y?<lioLC{ui0io_Vh)gne;pFk#9EYpW=d%?0z`gQ@wJz}I z$EHq zb7$`N2=rJa;%RF@)5Q@s9pDFwZKg-XvsfCNH#>AFud0R`r+nmss-qqyzD1I7(HY9u zY7w^$0sneChVM8kA*2G_Zn=T+tNV3_Ct+DxM)z33reHJE!-E6=E!BTSae5-}@I4mK zh;J$iE`-Qtj1j$fs6~9at(|VQ4YcCdUwhk4K3eFjUaW->sKZF2E!CVWr_V1rK(l`& ziD?5BJ^h`HQzGZ^#L08E>*x2Ov3f|bhb{=i(Ml0c>Ihjmx(lsDpW&(gnH(~iUzBj3 zu)Nj$aqS3dJrX9hC}_1}XNkAmzh5LCV#nWM2t%(zfxAE3z&L2=OtHenS?1zMaicTK zxkqu{4}DsD*wH1oO$iKV;l8J~)Ap+*K&}!>V^VG`TDS+J>U3f7TY6etgI<%e*U$MO z7E`j==ueLYPkY8J5v&%+h<5_<1?g;9{$IgAO=US{Ns-6yN^ zoyc@WpZm5xXIj}eS9y2^mR&dMVlhA0yvLBH;~B%Py&u2 zZ{;r)o$>sVy4ByQJ250xK*ZlPh;f}-Mvlsx3!Cj+5F&WV^>CNa9<=4C zO~U$Lv%$-=k)I7~t;8(fjyjLo*?M-fM}jL)u15r_h?HeU+;cmRax^j#ptCP|mVX4z z^IpoUCkv+fi%<(1Vz9WnO1}aD;U%6>1p_F+4D|0dLjGW+;* zyY4f;Y~|B}T|Es+)>t*(sXptQN)x<&HP#t6pGrqHd4JqzYvi+H_Bo!Bb@xDCoNdCA z!464gA^zQ`zbxPLwuubhq0`ELY5l?|O?V)QS4%ubvnctQ3J=A^2 z<&YG_GAD~WT)_qmLo-huCN(W?tsYaYBjUy!Zri9mFm>jW!b>!Zjk&~3>Af+CUI!i^ zZzQdDxU*lISg|d{q`oy@ED#n?8sp6npd>9q(68-?74-J&`AUy{R~181UQ+;HVc_rY zP<_>%rYn~;IjP(T1O zGt=thd7@5l)2EiFp6{4L{u2y#W*kf zDHFdz5M>^o=Kw@d;{3saRowlSnn_GrD%nZrr zvNt~A4Km&y+{K_dGM(mn>QCW^#O)t{C{@b3p^o8)SmV!6Z^;>I6$`b!t@>^jzQaVr za$SBj$RA$Gwyw2{;pbA7byB}92q%@+_vPj0BNS2la=y7dCe$&dOL?7h`L+}7ciuT& zLS5{ui06Ei4{NVS(PUm8Vd)o0vshl%MUHJzt)L!A%oxQT{z7jaY-l5ULI!f%qlZxQ zG#2EwMN5@J#w&7R%JV_rzmda~wN5tKEbK%v7Q(4jvMn=*Ypz)wnbs4NE3Tt@N((-U~*+|>I$z@%;v>hP_E+ z(VxEYSB}m+D>ve6(=*~xfhiVgw;bi7Cd!2-?vA9IOgI4#0Eg58#vrYipb1IHPdeyp zy$vOjm*UP@7f_q`^o!tn+wybzrV9$wK)JP#0nB2C8Zf5-P1j!;z=H2OidafL=ylD} z{x5XQ`DS;e(Z$rqRthhNMdM%b?>bdA-h8oAV;Jy~nGXk+(GRORN6OnJ`rFtLzFQtf)tN(m4( zauo8qcX+)&w7q^6;l z6rPta&m%A7xjrfAV@%ybRAS)T?ya)jnY!ntEt4ZIMt&=KpCXVdC3|y=`(Q95BRQkb zvsI}1g`%@IZt!2BE=($iPAkoUzdn=J0!!w$3a5%mPev1=+)YS%A!0YxuXaZFW$xYh zD`)`I9Es-fg~O;=FOkJ=tNUrm0R&2t3!mnjVTq7^i2XOwHQ8CMu@27Q^q0mei5V(+ zT-VcpYbKy%DA_RP^sI+KsR&L4o=ApVAG0bUHSj_u8~s78a>}Pcd)w{R)|>mG0}o)> zhVw1gv{70u4&;YARH}>ulm@^|Ko|JIB$f8l_E+hla409Q48ijCi9g_MZ%%z+jiGj{pgjmmdbsg+xD0I8>ZlDUnPzrI8l=M02BpTeOtEiV1iD5_Myn z4|m4l0pQhaMrjuk-ZS>$)Pt82%q|xLRF~>JLGpIF^v+yJsf9s$ZIprb#;03`dlu4Q z6<+@n27PtmSyNvYU}(AZcB$vy+hpdL8=-~|K_zo~GrdsHPyd)q!Rv$A=Gu19>!T!O z7AQox?`HheL3SE!oqBxl61(H^u+vbOQS`a8dP~SEQa%Tw@2myp@ps~9d#}viez+1I z`KL4#LvK{AanQx(rC#qsxCDI2w7Uu0q=Tnm@X74}!Jf8AJMZmQkNu zgS&HpxHtbxvP;ogx(`_V{yI;#0TwliFos<0Xa5Sh(g4y<{8{6@RU3;LsCEQP z1(-Ise3J}BT>MS}mcgE>e2zo=lVxYm%{@!(*%N3_)0`|9tBb%O5OcpZe*a!YoHt2N zY8at1HGCNdF0XkTh@m4SxP~@?t3vy5s*|*l{h`93=LCK$5aW`0OEcg51d#v!l~x>S2$AVmbKVR7Kf|^Gn*Pe7I()tW6s(Pby&Y z<*l+=|7-V=r3Hl;W=%C0`%3ea4{nK4k9kMmN0GYQUmLrbLvO~W>~`4d`z^EO&m;dn z^HoB`d}{!(%G!oNH&550S9A*ij^IOxKQ_DJb6Q9JH3DHA;t#=AZ$T;?a)^lEP??1P zlc<-Z(>%wVNYM5N{Nm$``xcGfWAb;=-BJm`_BZ=;d9`CFEkEaamz98%%+E zz_$dbf*~Ku9Yy)p0`|=BfA}tsqpUWXC(t$DDWvVT{Mo-t;)+x2|9QJgu*`}u_4l-I z?&}LbUb*8;o7}Yx`Ci66dk5CO{e3}UaVQ;>nz6iiP&9_jrGd|mP=x2FO+{Je)_z&d^y^#w%!Ob(Dn3E zQHi@U6Zl51kE~wv>EiKON!tD28%1X9uYi5WK9$>JF)!(G7vG?2d)NpA0C;&bzwe%L z-*D~BH`+E&`Dp&9hN8eMQsvvDIky#tdq;os-(>Nst$);F;$w80p2>Q@8V$Oq*qv3_ z(BuwUD1G3fGomT{$7-ybJbzm{Lq$F5nOYK8PGv;mSR)sA&wrvfWv8gC7f;UG(gdkB z1k`R2f__8ti=@{^82lf>Cb%@e#l3>k9KFee1zpX*TMVpxG^l2Jcn9>BimRFYJ&)P#{zWb#kUxXkU4yHs2Nwb=DJGo?6h z*GC$v0tN|5Os`=MQ4$_E|2e$TI+LR*8G-(N-OD}Q{-B24c5<4>x+n*=^41a*L!s3n$DVQ+%xEn=^LEn>t><1jM9ELl5;nhpDMZf{!M@9 zGDhJ;@nApi52qIt$-pLhtW!ekh@t24+An>^oDhsCuB=E((@o-jxbG5NYbg0C|4Dh? zEGJtY3aB@jaRi<_(BR0PL5S=t9Jd}d;Md<2Df~EmTWlqNN2~?hiOn@}E^wY>klA#d zWj~Wg{x$WO*!V-~M>oee$Pa%T`CPLg?O0g^o{=|YcvEi{X*Esc#mcVa8|Hs`b#kEa=2`zgzWg)_=IcW!fjiEy;8v?26GjS0&1|K4pQHTweHLKJfem<%uO_@`O_n6%B`p zxx1c@kcD#b`h0^&+Rv@6#m#G9UMJng-wKU&clBQ_VaSIUqd4zbBzNxoy%LSfPRcrBYNB!YpUz_7M*E;ehIKsGt#YfN{Q4vUhzO<>%NA|X%LUk+ zq(*Fne>z@fRSB*7Nt*asMr5D#02E@Gh!&40RF5)8YSL)y)d*VSz;?%va#`}ud-2>j z0DHgt#go9rR1AK?!U}tA_FJ!op#(LCb37tZFp6_m;Bxo^hJzDTNKEAjDQjPC<^SW$(a%X@1E2{@gZ z7K0ZFg;~X)QosiAWMkf4HFT2hSMR24SnNarQEc`Nl2=fEXU)xrs*pf2Pr0maU7XeN zu`%r3p-yROXa)4<_3KAjpW#`T_rk=#u5G!JT>AwtDJ5+LBf|?HYg%=QTG5{v!=5Q< z)RYocpzahC{L-Eg27cWu%)4VU#rt!(B#-|?A1)9X$2rhXtNgwSd=z3Zs#j48&)-5rt{1k<4tZc1O;l=z#dX!!*DSNyRun?qM*9a=JO!t^L}l-m>5=0ecmnCjHVMf9XH zJNEr?@g!#8UzG--WP?+y3k;t`d8ENywBP^al8_;eGc|yof80>P%-~O&Pqj9u!*JYe`JT7nzlN+_O2?H!3EUoJP)go35FxgM$GHu_F?ea5y* zL`4kvBwlBkqlkRWkE+qvl}!4qZh0&>p%jo=AR2C~&I8BX?@@UZ)Q6n!s8rX1ZT@2H zZwc~uOgQ@kC+|scl;IE<|JH`qflMWnruS-}S9AWXDRuheMAZr{vA&ZhcfD;*_2@OW zMc*@SX!6qTJ~tFCg369B!cRW4#^+HoR&?0P5llnB<7KvRbWRrqo-Gk^jZ*BIQ-JDS zMd7z~PNp~&I~?a|W6>6zUFJ$l&Zr&3b+in3w|^6EL@?;CM+t|?nK9A^Ean2t@MCM*V8F_Nwt`?9BHlC9hb&k zX$gXf>jCguC!I=aZZgrVV!j^;l5q}D_$peCijbVkt5$cu`hxNvTETPC)yz@gVn&y1 zut~`r@X&nU`GcZBiip7~R(mmiYZ;Q#Hr0W&&$H~#!6p+@X~k)-S}FLAR`jxV>d`I zsNO;=w|V1Epgp1Cp%$HZ>)bdFg;^MTkZBHdb#b)Q37s&Z=NB(~`ewTG^_-yZj~ZSr zRx06jI-hQDB8&djKGEi$q`5*0e91X85yWpk^avUc1RbZj@ch;{i=3a6k(VfXX zH3L>qx*Kwz_H*2V*Y^B;0DQHGstRUF*eL?8<-bYw@yFFpMN!!Xsceb5bCG0_3QbG^ z{%ON8;4962xf8OzJN{o#WXx(67x8gbZAu7WnpUyLYdF)deu>S+9d&eF$ zKezvWbPbHA7U^XN_=@0m_i9c|*`AMx_&!RA29i$z`q`{IbBAcJZ{4)7J$shrEJw=L zuKc7x&2c`s!ITHlmM_wFRW(l>A*zL!hDmu2MRhJpoS}Ls)u%+w>KT7j8{B%I?dZ2y+roq-uJx z6kNWmxA=%lXhSFRsnm~OzgRe{ca=$|W0R+#nrJDJ6G;`Q#P*%AZ=EFFQexX`aMd5Y z{1$?!ph;t?^iVNFYs52Q`1Omai#*ldAE-r~s;FGce&~&|6ocwwKMjJAg%;Ja(?jz_ zw;w0?)0qEtd!&EpU) z^ldHDqnEcxXOqC(s*qRgD_WKFPfVYsWno=zG=3Kqb%Y+W}X^J6vNas+n(HMezB0)sp ziw};IfuWe3=?jf=T=DGPPzxy!&n;qhf3V;u)p>ms_}2)7d8o#=pWHQHi6R#o1-?{C zwYlJW#1#OClT|;QD>fSDZWLvB?3@3Ak8wF}O5Z{J?#!RBz5`=z1PMyfZ^}SwVduD) zSsa4%3r)~tbUQoX?Oje?wlTt9?_A^kWAR>6XFXO=FQf(J%^kjoY?WElV!hTSRZ*PE zQIfo!tRt;$Y2U*tqV)5<;3})~JCVZsZ%f|m7HX;)+_SbTrqqqNXX6;Doq-X?#eT4- zD`)7DAACJ=@$FT)@fn;=m5s1bx`Kz|i=h!6JY%rrM70!Gm&ZwLrxDMb&A*9?PcKTiZ&zEUVo!>%c zKYJPT`kW?mXRjeowp!9eVe{E2|0PT%84Z_eIf)eC9V0>auX ztGgU*(lgapNid6E8@xE2x%%TZWSRG~fO3i7+mV(wE^u4BA#=H0B|7DQu7N(8mF5bp zlGo9zfrrCs1E&U(48;5*YIQnYUx0@le9B+?V9gs_*MwG`w5s30R7D!Hmv>8dP+~kU5c2t-#k8oL=8lk+D~=b8YaixpvEE{LUP0NzHe@nOF0%B+VmZ>qx^^ zJZADS1W$R{;BT9Mp{=hiZKqnH2Qv7mO7)RVq(9W!!-l}WMFquN14$KGB@!wlA}j$b{R zQ8rEK5yThrmwaFoW=muwbUr?1&A2$h+MeUhX~z?0@CC<2GPfQXUFs!v;z?((Q|IH4 z&yT*PC*!0w6uQ=dL;CdTj=bZen%e%*9( zXCjO3Z|WW$67Kg2`V2#fv_emyn@H&OizJrx*wn>;H93ddvv`sWUbT|m&(?}Qbqdd} z5SM)Zl6Oy!Nb8H6T6)3f$2Y9c@#2ACB==GUUj&qBq|{XL_T zqXhm~KQfF-Mctm|o&ejcF}B)3kogJJrOV`T(=#ldaf9&cJ9*7Sqv`k8Of0klDw*1B z7Wctmb? z;0s{&{0RB-(bSn*4)aM|tpH!^bvO6eW*gQkp+6boZkHVWUoeL1;&B@uCBDs4!eRSW z(ekmn;nIAmxGEBL`R0*Q;=}H7wi4?YXLb!e@63V`^g57I+VYTKxgO`t8W9TnkR(zu z%G5`!NUFA~N5W*UcVj-()Q;R&WUAOAQA|P&cE`fvlh^GrsU*mkWg(P4J}Gzd0M0=r z_zqs5%mVU|-Ev+9XtDRl7IbFyx=?9Ta6+-pdGhzkgK1iPNzMWl;PB{te-Jni=G2n7 zv@eVlA}%dms9e7FplQE-J`I(_%GDJ(Gu~73LS)5OEKj% z7|`~Y{WN-&6VzE3g<@37WwfCiONgF6h|5DPdI9}62FK4AeV%os4@+k#K;LTJpLpYhlxUjw<%g|36mM~sP#bW|YJ zflxm{Cqw*4_Ie%gE5Mx&KnJ{=D4BfY|KKi$2|Z(9-T~LZXYb(Y!2?v_K_uYm9esYz z2p&{EIq%{Ghe(0*hJMH)iwb0I?nD`Yi0|0oKh3~2U#C>uGJ1fq?Rj)^fyuZCx6(D9 zx-WnFG#~x5e3`DP!Zu6&?aozoYKbefO^pntQW94Lu1NDo?Iz^sX~$mOw6^z!uIwk} zR@;|O|IPTjifxJbZVjAa-A6pDy~@@}j!*_9*no#nQIYJ5t3Dl8CKXEGz)Mj)f2PlI z)F2R!&*=xut#e83H2*jLh-dGI64hc!OFx%Xa&xe2CB8bsoE)p?*jyqx$s9lPBJam+rLIb!<>Z|W}Ji_RZ|JJ=lbEJ3I>*We!` z;Ps=1C3>vPcMOz3y7xjqI|GqdhwF0!z_21<*$#5!G<{f3(1TPVAgpRXDyi2enm+mj@qBUdPHLK&&je<+E9U z+>vAjo(musRA1Sb2M3aJ3x&GKAy6M2IX%17OOAh!-(81`@`y`Fs24^8f6p4k&Tj)3 zSe;2_j!{F4b5&4e;qHp740M>O=ARwGUv{(xKiZ#GV8G4|1G2(;S$RTT^#}@497icB zHz0$}IvKb^G5!0lmPs#42kF8Es2(AUU(4wEo>5`XianHj(b0X-!L~7Whw5lwCkHnG zy|Et*cqXZOI?3q*wokF^A+YI5J6e6?YU{{u8K9%-pEUw&JJVcKkPUx0We#>38fH%F zfL1#;R+kp`0-&nMLzA!qWVP;o_r%7dU-G5fw@kyp-Jr0hBThmIihKJ7NLTT8e!4IY z>`)|lZ;1kxE*BX|+N;o0uL@Rh4E~}NHG-en&h7(v1bH4#Q-DpRzo7%))c*+@i4u|1 zaCuLFpHEkC9yO#wVZTp;(;b$ua5I+%^Dr!p!Y^Ga zEV(dLsXHFzXLg~aDPX9|)DHtif z%l_Q9VojB4Qu~P;d$iM{LpzL8%8MKafOh*9!tIs${qn_!{*sr*{`>Zh0Dm|<&~>v; zj{{sbdLU*}41~%~m6KiU3Mm6-HyYo4EMHh#k?`B-tdiEAAP%D#}IZG;F-CKQYoU&=# zZ$9ssJA+(2g1&O) zvEFmqnT$s!kT4EGiKrG2Y~#`IM~l&%K_+o}7}fa5Ae_`iiG2mx0(W-9yZ_HpR7~g$ z@G2HDk+Ze&+A!6|_)dFoeV+LbdU_?Z@*9GU2o+d8^XAbT7<07jDAy#9U`r9FGXUrQ@vYKj$_HfU9)~>cYHyN5MG^&Y+RVV`qVnE zVlJ|IGk1H!J=-)L%3Y645FlMhQ-s_wb$#d0or(DSXeTj$1`Z>}s-5&vW1uF;9eshF z{MQhm^jYlqo)k?`FUCS|dKhzzNFrheu;aF+Q&?-9_8x{07ClLj3H%KBeOS;-Higcd dzT($^2@}F