0
# Configuration
1
2
Comprehensive behavior management for performance tuning and feature configuration. pylibmc provides extensive configuration options through behaviors, hash algorithms, distribution methods, and connection parameters.
3
4
## Capabilities
5
6
### Behavior Management
7
8
Configure client behavior for optimal performance and functionality. Behaviors control everything from network timeouts to hashing algorithms.
9
10
```python { .api }
11
def get_behaviors() -> dict:
12
"""
13
Get current behavior settings with symbolic names.
14
15
Returns:
16
dict: Current behaviors with string keys and appropriate values
17
"""
18
19
def set_behaviors(behaviors: dict):
20
"""
21
Set behavior configuration options.
22
23
Parameters:
24
- behaviors (dict): Behavior name to value mapping
25
26
Raises:
27
- ValueError: For unknown behavior names or invalid values
28
"""
29
30
@property
31
def behaviors() -> BehaviorDict:
32
"""
33
Behavior dictionary property that syncs changes to client.
34
Allows both getting and setting behaviors via dict interface.
35
36
Returns:
37
BehaviorDict: Special dict that updates client on changes
38
"""
39
```
40
41
### Hash Algorithms
42
43
Configure hashing algorithms for key distribution across multiple servers.
44
45
```python { .api }
46
# Hash algorithm constants
47
hashers: dict = {
48
"default": hash_default,
49
"md5": hash_md5,
50
"crc": hash_crc,
51
"fnv1_64": hash_fnv1_64,
52
"fnv1a_64": hash_fnv1a_64,
53
"fnv1_32": hash_fnv1_32,
54
"fnv1a_32": hash_fnv1a_32,
55
"murmur": hash_murmur,
56
"hsieh": hash_hsieh,
57
"jenkins": hash_jenkins
58
}
59
60
hashers_rvs: dict # Reverse mapping: constant to name
61
```
62
63
### Distribution Algorithms
64
65
Configure distribution algorithms for spreading keys across server clusters.
66
67
```python { .api }
68
# Distribution algorithm constants
69
distributions: dict = {
70
"modula": distribution_modula,
71
"consistent": distribution_consistent,
72
"random": distribution_random,
73
"consistent ketama": distribution_consistent_ketama,
74
"consistent ketama spy": distribution_consistent_ketama_spy,
75
"consistent weighted": distribution_consistent_weighted,
76
"virtual bucket": distribution_virtual_bucket,
77
"consistent max": distribution_consistent_max
78
}
79
80
distributions_rvs: dict # Reverse mapping: constant to name
81
```
82
83
### Available Behaviors
84
85
Complete list of configurable behaviors and callbacks.
86
87
```python { .api }
88
all_behaviors: list = [
89
"auto_eject",
90
"buffer_requests",
91
"cas",
92
"connect_timeout",
93
"distribution",
94
"failure_limit",
95
"hash",
96
"ketama",
97
"ketama_hash",
98
"ketama_weighted",
99
"no_block",
100
"num_replicas",
101
"pickle_protocol",
102
"receive_timeout",
103
"retry_timeout",
104
"send_timeout",
105
"tcp_keepalive",
106
"tcp_nodelay",
107
"verify_keys"
108
]
109
110
all_callbacks: list = [
111
"namespace"
112
]
113
```
114
115
### BehaviorDict Class
116
117
Special dictionary class that automatically syncs behavior changes to the client.
118
119
```python { .api }
120
class BehaviorDict(dict):
121
"""
122
Dictionary that syncs behavior changes to client automatically.
123
Inherits from dict with additional client synchronization.
124
"""
125
126
def __init__(client, *args, **kwargs):
127
"""
128
Initialize behavior dictionary.
129
130
Parameters:
131
- client: Client instance to sync changes to
132
- args, kwargs: Standard dict initialization arguments
133
"""
134
135
def __setitem__(name: str, value):
136
"""
137
Set behavior and sync to client.
138
139
Parameters:
140
- name (str): Behavior name
141
- value: Behavior value
142
"""
143
144
def update(d: dict):
145
"""
146
Update multiple behaviors and sync to client.
147
148
Parameters:
149
- d (dict): Behaviors to update
150
"""
151
```
152
153
### Configuration Utilities
154
155
Helper functions for configuration management.
156
157
```python { .api }
158
def translate_server_spec(server: str, port: int = 11211, weight: int = 1) -> tuple:
159
"""
160
Parse server specification string into connection tuple.
161
162
Parameters:
163
- server (str): Server specification (host:port, /path/to/socket, etc.)
164
- port (int): Default port if not specified
165
- weight (int): Server weight for consistent hashing
166
167
Returns:
168
tuple: (server_type, address, port, weight)
169
"""
170
171
def translate_server_specs(servers: list) -> list:
172
"""
173
Parse list of server specifications.
174
175
Parameters:
176
- servers (list): List of server specifications
177
178
Returns:
179
list: List of parsed server tuples
180
"""
181
```
182
183
## Configuration Categories
184
185
### Network and Connection Behaviors
186
187
```python
188
# Connection timeouts (milliseconds)
189
client.behaviors.update({
190
"connect_timeout": 5000, # Connection establishment timeout
191
"send_timeout": 5000, # Send operation timeout
192
"receive_timeout": 5000, # Receive operation timeout
193
"retry_timeout": 30, # Retry failed servers after N seconds
194
})
195
196
# Network optimization
197
client.behaviors.update({
198
"tcp_nodelay": True, # Disable Nagle's algorithm
199
"tcp_keepalive": True, # Enable TCP keepalive
200
"no_block": True, # Non-blocking I/O operations
201
"buffer_requests": True, # Buffer multiple requests
202
})
203
```
204
205
### Hashing and Distribution
206
207
```python
208
# Hash algorithm selection
209
client.behaviors.update({
210
"hash": "fnv1a_64", # Use FNV1a 64-bit hash
211
"ketama_hash": "md5", # Hash for ketama distribution
212
})
213
214
# Distribution algorithm
215
client.behaviors.update({
216
"distribution": "consistent ketama", # Consistent hashing
217
"ketama": True, # Enable ketama consistent hashing
218
"ketama_weighted": True, # Weight servers by memory
219
"num_replicas": 160, # Virtual nodes per server
220
})
221
```
222
223
### Reliability and Failover
224
225
```python
226
# Server failure handling
227
client.behaviors.update({
228
"auto_eject": True, # Remove failed servers automatically
229
"failure_limit": 3, # Max failures before server ejection
230
})
231
```
232
233
### Protocol and Serialization
234
235
```python
236
# Protocol options
237
client.behaviors.update({
238
"cas": True, # Enable Compare-And-Store support
239
"verify_keys": True, # Validate key format
240
})
241
242
# Serialization
243
client.behaviors.update({
244
"pickle_protocol": 2, # Python pickle protocol version
245
})
246
```
247
248
## Usage Examples
249
250
### Basic Configuration
251
252
```python
253
import pylibmc
254
255
# Create client with behaviors
256
client = pylibmc.Client(["localhost:11211"], binary=True)
257
258
# Set behaviors for optimal performance
259
client.behaviors = {
260
"tcp_nodelay": True,
261
"ketama": True,
262
"no_block": True,
263
"connect_timeout": 5000,
264
"retry_timeout": 30
265
}
266
267
# Check current configuration
268
print("Current behaviors:", client.behaviors)
269
```
270
271
### High-Performance Configuration
272
273
```python
274
import pylibmc
275
276
client = pylibmc.Client(["server1:11211", "server2:11211"], binary=True)
277
278
# Optimize for high-throughput scenarios
279
high_perf_behaviors = {
280
# Network optimization
281
"tcp_nodelay": True,
282
"no_block": True,
283
"buffer_requests": True,
284
285
# Consistent hashing for even distribution
286
"distribution": "consistent ketama",
287
"ketama": True,
288
"hash": "fnv1a_64",
289
"ketama_hash": "md5",
290
291
# Fast failover
292
"auto_eject": True,
293
"failure_limit": 2,
294
"retry_timeout": 10,
295
296
# Reasonable timeouts
297
"connect_timeout": 2000,
298
"send_timeout": 2000,
299
"receive_timeout": 2000,
300
}
301
302
client.behaviors.update(high_perf_behaviors)
303
```
304
305
### Multi-Server Cluster Configuration
306
307
```python
308
import pylibmc
309
310
# Define server cluster with weights
311
servers = [
312
("server1.cache.local", 11211, 1), # Standard weight
313
("server2.cache.local", 11211, 2), # Double weight (more memory)
314
("server3.cache.local", 11211, 1),
315
]
316
317
client = pylibmc.Client(servers, binary=True)
318
319
# Configure for cluster reliability
320
cluster_behaviors = {
321
# Consistent hashing with weights
322
"distribution": "consistent ketama",
323
"ketama": True,
324
"ketama_weighted": True,
325
"num_replicas": 160,
326
327
# Robust failure handling
328
"auto_eject": True,
329
"failure_limit": 3,
330
"retry_timeout": 60,
331
332
# Conservative timeouts for stability
333
"connect_timeout": 5000,
334
"send_timeout": 10000,
335
"receive_timeout": 10000,
336
}
337
338
client.behaviors.update(cluster_behaviors)
339
```
340
341
### Development vs Production Configurations
342
343
```python
344
import pylibmc
345
import os
346
347
def create_client(servers, environment="development"):
348
"""Create client with environment-specific configuration."""
349
350
client = pylibmc.Client(servers, binary=True)
351
352
if environment == "development":
353
# Development: Faster timeouts, more verbose errors
354
client.behaviors.update({
355
"connect_timeout": 1000,
356
"send_timeout": 1000,
357
"receive_timeout": 1000,
358
"retry_timeout": 5,
359
"verify_keys": True,
360
"tcp_nodelay": True,
361
})
362
else:
363
# Production: Conservative timeouts, high performance
364
client.behaviors.update({
365
"connect_timeout": 5000,
366
"send_timeout": 5000,
367
"receive_timeout": 5000,
368
"retry_timeout": 30,
369
"tcp_nodelay": True,
370
"no_block": True,
371
"buffer_requests": True,
372
"auto_eject": True,
373
"failure_limit": 3,
374
"ketama": True,
375
"distribution": "consistent ketama",
376
})
377
378
return client
379
380
# Usage
381
dev_client = create_client(["localhost:11211"], "development")
382
prod_client = create_client(["cache1:11211", "cache2:11211"], "production")
383
```
384
385
### Behavior Validation
386
387
```python
388
import pylibmc
389
390
client = pylibmc.Client(["localhost:11211"])
391
392
# Validate behavior settings
393
def validate_behaviors(client):
394
"""Check if client has recommended behaviors."""
395
behaviors = client.get_behaviors()
396
397
recommendations = {
398
"tcp_nodelay": True,
399
"ketama": True,
400
"connect_timeout": lambda x: 1000 <= x <= 10000,
401
"retry_timeout": lambda x: x >= 10,
402
}
403
404
for behavior, expected in recommendations.items():
405
current = behaviors.get(behavior)
406
407
if callable(expected):
408
valid = expected(current) if current is not None else False
409
else:
410
valid = current == expected
411
412
status = "✓" if valid else "✗"
413
print(f"{status} {behavior}: {current}")
414
415
validate_behaviors(client)
416
```
417
418
## Server Type Constants
419
420
```python { .api }
421
server_type_tcp: int # TCP connection (value: 1)
422
server_type_udp: int # UDP connection (value: 2)
423
server_type_unix: int # Unix socket connection (value: 4)
424
```
425
426
## Feature Detection
427
428
```python { .api }
429
support_compression: bool # Whether zlib compression is available
430
support_sasl: bool # Whether SASL authentication is available
431
libmemcached_version: str # Version of underlying libmemcached
432
```