1 '\" te
2 .\" Copyright 2015 Nexenta Systems, Inc. All rights reserved.
3 .\" Copyright 2022 Joyent, Inc.
4 .\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved.
5 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
7 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
8 .TH KMEM_CACHE_CREATE 9F "Feb 18, 2015"
9 .SH NAME
10 kmem_cache_create, kmem_cache_alloc, kmem_cache_free, kmem_cache_destroy,
11 kmem_cache_set_move \- kernel memory cache allocator operations
12 .SH SYNOPSIS
13 .nf
14 #include <sys/types.h>
15 #include <sys/kmem.h>
16
17 \fBkmem_cache_t *\fR\fBkmem_cache_create\fR(\fBchar *\fR\fIname\fR, \fBsize_t\fR \fIbufsize\fR,
18 \fBsize_t\fR \fIalign\fR, \fBint\fR (*\fIconstructor\fR)(void *, void *, int),
19 \fBvoid\fR (*\fIdestructor\fR)(void *, void *), \fBvoid\fR (*\fIreclaim\fR)(void *),
20 \fBvoid\fR *\fIprivate\fR, \fBvoid\fR *\fIvmp\fR, \fBint\fR \fIcflags\fR);
21 .fi
22
23 .LP
24 .nf
25 \fBvoid\fR \fBkmem_cache_destroy\fR(\fBkmem_cache_t\fR *\fIcp\fR);
26 .fi
27
28 .LP
29 .nf
30 \fBvoid *\fR\fBkmem_cache_alloc\fR(\fBkmem_cache_t\fR *\fIcp\fR, \fBint\fR \fIkmflag\fR);
31 .fi
32
33 .LP
34 .nf
35 \fBvoid\fR \fBkmem_cache_free\fR(\fBkmem_cache_t\fR *\fIcp\fR, \fBvoid\fR *\fIobj\fR);
36 .fi
37
38 .LP
39 .nf
40 \fBvoid\fR \fBkmem_cache_set_move\fR(\fBkmem_cache_t\fR *\fIcp\fR, \fBkmem_cbrc_t\fR (*\fImove\fR)(\fBvoid\fR *,
41 \fBvoid\fR *, \fBsize_t\fR *, \fBvoid\fR *));
42 .fi
43
44 .LP
45 .nf
46 [Synopsis for callback functions:]
47 .fi
48
49 .LP
50 .nf
51 \fBint\fR (*\fIconstructor\fR)(\fBvoid\fR *\fIbuf\fR, \fBvoid\fR *\fIuser_arg\fR, \fBint\fR \fIkmflags\fR);
52 .fi
53
54 .LP
55 .nf
56 \fBvoid\fR (*\fIdestructor\fR)(\fBvoid\fR *\fIbuf\fR, \fBvoid\fR *\fIuser_arg\fR);
57 .fi
58
59 .LP
60 .nf
61 \fBkmem_cbrc_t\fR (*\fImove\fR)(\fBvoid\fR *\fIold\fR, \fBvoid\fR *\fInew\fR, \fBsize_t\fR \fIbufsize\fR,
62 \fBvoid\fR *\fIuser_arg\fR);
63 .fi
64
65 .SH INTERFACE LEVEL
66 illumos DDI specific (illumos DDI)
67 .SH PARAMETERS
68 The parameters for the \fBkmem_cache_*\fR functions are as follows:
69 .sp
70 .ne 2
71 .na
72 \fB\fIname\fR\fR
73 .ad
74 .RS 15n
75 Descriptive name of a \fBkstat\fR(9S) structure of class \fBkmem_cache\fR.
76 Names longer than 31 characters are truncated.
77 .RE
78
79 .sp
80 .ne 2
81 .na
82 \fB\fIbufsize\fR\fR
83 .ad
84 .RS 15n
85 Size of the objects it manages.
86 .RE
87
88 .sp
89 .ne 2
90 .na
91 \fB\fIalign\fR\fR
92 .ad
93 .RS 15n
94 Required object alignment.
95 .RE
96
97 .sp
98 .ne 2
99 .na
100 \fB\fIconstructor\fR\fR
101 .ad
102 .RS 15n
103 Pointer to an object constructor function. Parameters are defined below.
104 .RE
105
106 .sp
107 .ne 2
108 .na
109 \fB\fIdestructor\fR\fR
110 .ad
111 .RS 15n
112 Pointer to an object destructor function. Parameters are defined below.
113 .RE
114
115 .sp
116 .ne 2
117 .na
118 \fB\fIreclaim\fR\fR
119 .ad
120 .RS 15n
121 Drivers should pass \fBNULL\fR.
122 .RE
123
124 .sp
125 .ne 2
126 .na
127 \fB\fIprivate\fR\fR
128 .ad
129 .RS 15n
130 Pass-through argument for constructor/destructor.
131 .RE
132
133 .sp
134 .ne 2
135 .na
136 \fB\fIvmp\fR\fR
137 .ad
138 .RS 15n
139 Drivers should pass \fBNULL\fR.
140 .RE
141
142 .sp
143 .ne 2
144 .na
145 \fB\fIcflags\fR\fR
146 .ad
147 .RS 15n
148 Drivers must pass 0.
149 .RE
150
151 .sp
152 .ne 2
153 .na
154 \fB\fIkmflag\fR\fR
155 .ad
156 .RS 15n
157 Possible flags are:
158 .sp
159 .ne 2
160 .na
161 \fB\fBKM_SLEEP\fR\fR
162 .ad
163 .RS 15n
164 Allow sleeping (blocking) until memory is available.
165 .RE
166
167 .sp
168 .ne 2
169 .na
170 \fB\fBKM_NOSLEEP\fR\fR
171 .ad
172 .RS 15n
173 Return NULL immediately if memory is not available, but after an aggressive
174 reclaiming attempt. Any mention of \fBKM_NOSLEEP\fR without mentioning
175 \fBKM_NOSLEEP_LAZY\fR (see below) applies to both values.
176 .RE
177
178 .sp
179 .ne 2
180 .na
181 \fB\fBKM_NOSLEEP_LAZY\fR\fR
182 .ad
183 .RS 15n
184 Return NULL immediately if memory is not available, without the aggressive
185 reclaiming attempt. This is actually two flags combined:
186 (\fBKM_NOSLEEP\fR | \fBKM_NORMALPRI\fR), the latter flag indicating not to
187 attempt reclamation before giving up and returning NULL.
188 .RE
189
190 .sp
191 .ne 2
192 .na
193 \fB\fBKM_PUSHPAGE\fR\fR
194 .ad
195 .RS 15n
196 Allow the allocation to use reserved memory.
197 .RE
198
199 .RE
200
201 .sp
202 .ne 2
203 .na
204 \fB\fIobj\fR\fR
205 .ad
206 .RS 15n
207 Pointer to the object allocated by \fBkmem_cache_alloc()\fR.
208 .RE
209
210 .sp
211 .ne 2
212 .na
213 \fB\fImove\fR\fR
214 .ad
215 .RS 15n
216 Pointer to an object relocation function. Parameters are defined below.
217 .RE
218
219 .sp
220 .LP
221 The parameters for the callback constructor function are as follows:
222 .sp
223 .ne 2
224 .na
225 \fB\fBvoid *\fIbuf\fR\fR\fR
226 .ad
227 .RS 18n
228 Pointer to the object to be constructed.
229 .RE
230
231 .sp
232 .ne 2
233 .na
234 \fB\fBvoid *\fIuser_arg\fR\fR\fR
235 .ad
236 .RS 18n
237 The \fIprivate\fR parameter from the call to \fBkmem_cache_create()\fR; it is
238 typically a pointer to the soft-state structure.
239 .RE
240
241 .sp
242 .ne 2
243 .na
244 \fB\fBint \fIkmflags\fR\fR\fR
245 .ad
246 .RS 18n
247 Propagated \fIkmflag\fR values.
248 .RE
249
250 .sp
251 .LP
252 The parameters for the callback destructor function are as follows:
253 .sp
254 .ne 2
255 .na
256 \fB\fBvoid *\fIbuf\fR\fR\fR
257 .ad
258 .RS 18n
259 Pointer to the object to be deconstructed.
260 .RE
261
262 .sp
263 .ne 2
264 .na
265 \fB\fBvoid *\fIuser_arg\fR\fR\fR
266 .ad
267 .RS 18n
268 The \fIprivate\fR parameter from the call to \fBkmem_cache_create()\fR; it is
269 typically a pointer to the soft-state structure.
270 .RE
271
272 .sp
273 .LP
274 The parameters for the callback \fBmove()\fR function are as follows:
275 .sp
276 .ne 2
277 .na
278 \fB\fBvoid *\fIold\fR\fR\fR
279 .ad
280 .RS 18n
281 Pointer to the object to be moved.
282 .RE
283
284 .sp
285 .ne 2
286 .na
287 \fB\fBvoid *\fInew\fR\fR\fR
288 .ad
289 .RS 18n
290 Pointer to the object that serves as the copy destination for the contents of
291 the old parameter.
292 .RE
293
294 .sp
295 .ne 2
296 .na
297 \fB\fBsize_t \fIbufsize\fR\fR\fR
298 .ad
299 .RS 18n
300 Size of the object to be moved.
301 .RE
302
303 .sp
304 .ne 2
305 .na
306 \fB\fBvoid *\fIuser_arg\fR\fR\fR
307 .ad
308 .RS 18n
309 The private parameter from the call to \fBkmem_cache_create()\fR; it is
310 typically a pointer to the \fBsoft-state\fR structure.
311 .RE
312
313 .SH DESCRIPTION
314 In many cases, the cost of initializing and destroying an object exceeds the
315 cost of allocating and freeing memory for it. The functions described here
316 address this condition.
317 .sp
318 .LP
319 Object caching is a technique for dealing with objects that are:
320 .RS +4
321 .TP
322 .ie t \(bu
323 .el o
324 frequently allocated and freed, and
325 .RE
326 .RS +4
327 .TP
328 .ie t \(bu
329 .el o
330 have setup and initialization costs.
331 .RE
332 .sp
333 .LP
334 The idea is to allow the allocator and its clients to cooperate to preserve the
335 invariant portion of an object's initial state, or constructed state, between
336 uses, so it does not have to be destroyed and re-created every time the object
337 is used. For example, an object containing a mutex only needs to have
338 \fBmutex_init()\fR applied once, the first time the object is allocated. The
339 object can then be freed and reallocated many times without incurring the
340 expense of \fBmutex_destroy()\fR and \fBmutex_init()\fR each time. An object's
341 embedded locks, condition variables, reference counts, lists of other objects,
342 and read-only data all generally qualify as constructed state. The essential
343 requirement is that the client must free the object (using
344 \fBkmem_cache_free()\fR) in its constructed state. The allocator cannot enforce
345 this, so programming errors will lead to hard-to-find bugs.
346 .sp
347 .LP
348 A driver should call \fBkmem_cache_create()\fR at the time of \fB_init\fR(9E)
349 or \fBattach\fR(9E), and call the corresponding \fBkmem_cache_destroy()\fR at
350 the time of \fB_fini\fR(9E) or \fBdetach\fR(9E).
351 .sp
352 .LP
353 \fBkmem_cache_create()\fR creates a cache of objects, each of size
354 \fIbufsize\fR bytes, aligned on an \fIalign\fR boundary. Drivers not requiring
355 a specific alignment can pass 0. \fIname\fR identifies the cache for statistics
356 and debugging. \fIconstructor\fR and \fIdestructor\fR convert plain memory into
357 objects and back again; \fIconstructor\fR can fail if it needs to allocate
358 memory but cannot. \fIprivate\fR is a parameter passed to the constructor and
359 destructor callbacks to support parameterized caches (for example, a pointer to
360 an instance of the driver's soft-state structure). To facilitate debugging,
361 \fBkmem_cache_create()\fR creates a \fBkstat\fR(9S) structure of class
362 \fBkmem_cache\fR and name \fIname\fR. It returns an opaque pointer to the
363 object cache.
364 .sp
365 .LP
366 \fBkmem_cache_alloc()\fR gets an object from the cache. The object will be in
367 its constructed state. \fIkmflag\fR has either \fBKM_SLEEP\fR or
368 \fBKM_NOSLEEP\fR set, indicating whether it is acceptable to wait for memory
369 if none is currently available.
370 .sp
371 .LP
372 A small pool of reserved memory is available to allow the system to progress
373 toward the goal of freeing additional memory while in a low memory situation.
374 The \fBKM_PUSHPAGE\fR flag enables use of this reserved memory pool on an
375 allocation. This flag can be used by drivers that implement \fBstrategy\fR(9E)
376 on memory allocations associated with a single I/O operation. The driver
377 guarantees that the I/O operation will complete (or timeout) and, on
378 completion, that the memory will be returned. The \fBKM_PUSHPAGE\fR flag should
379 be used only in \fBkmem_cache_alloc()\fR calls. All allocations from a given
380 cache should be consistent in their use of the flag. A driver that adheres to
381 these restrictions can guarantee progress in a low memory situation without
382 resorting to complex private allocation and queuing schemes. If
383 \fBKM_PUSHPAGE\fR is specified, \fBKM_SLEEP\fR can also be used without causing
384 deadlock.
385 .sp
386 .LP
387 \fBkmem_cache_free()\fR returns an object to the cache. The object must be in
388 its constructed state.
389 .sp
390 .LP
391 \fBkmem_cache_destroy()\fR destroys the cache and releases all associated
392 resources. All allocated objects must have been previously freed.
393 .sp
394 .LP
395 \fBkmem_cache_set_move()\fR registers a function that the allocator may call to
396 move objects from sparsely allocated pages of memory so that the system can
397 reclaim pages that are tied up by the client. Since caching objects of the same
398 size and type already makes severe memory fragmentation unlikely, there is
399 generally no need to register such a function. The idea is to make it possible
400 to limit worst-case fragmentation in caches that exhibit a tendency to become
401 highly fragmented. Only clients that allocate a mix of long- and short-lived
402 objects from the same cache are prone to exhibit this tendency, making them
403 candidates for a \fBmove()\fR callback.
404 .sp
405 .LP
406 The \fBmove()\fR callback supplies the client with two addresses: the allocated
407 object that the allocator wants to move and a buffer selected by the allocator
408 for the client to use as the copy destination. The new parameter is an
409 allocated, constructed object ready to receive the contents of the old
410 parameter. The \fIbufsize\fR parameter supplies the size of the object, in case
411 a single move function handles multiple caches whose objects differ only in
412 size. Finally, the private parameter passed to the constructor and destructor
413 is also passed to the \fBmove()\fR callback.
414 .sp
415 .LP
416 Only the client knows about its own data and when it is a good time to move it.
417 The client cooperates with the allocator to return unused memory to the system,
418 and the allocator accepts this help at the client's convenience. When asked to
419 move an object, the client can respond with any of the following:
420 .sp
421 .in +2
422 .nf
423 typedef enum kmem_cbrc {
424 KMEM_CBRC_YES,
425 KMEM_CBRC_NO,
426 KMEM_CBRC_LATER,
427 KMEM_CBRC_DONT_NEED,
428 KMEM_CBRC_DONT_KNOW
429 } kmem_cbrc_t;
430 .fi
431 .in -2
432 .sp
433
434 .sp
435 .LP
436 The client must not explicitly free either of the objects passed to the
437 \fBmove()\fR callback, since the allocator wants to free them directly to the
438 slab layer (bypassing the per-CPU magazine layer). The response tells the
439 allocator which of the two object parameters to free:
440 .sp
441 .ne 2
442 .na
443 \fB\fBKMEM_CBRC_YES\fR\fR
444 .ad
445 .RS 23n
446 The client moved the object; the allocator frees the old parameter.
447 .RE
448
449 .sp
450 .ne 2
451 .na
452 \fB\fBKMEM_CBRC_NO\fR\fR
453 .ad
454 .RS 23n
455 The client refused to move the object; the allocator frees the new parameter
456 (the unused copy destination).
457 .RE
458
459 .sp
460 .ne 2
461 .na
462 \fB\fBKMEM_CBRC_LATER\fR\fR
463 .ad
464 .RS 23n
465 The client is using the object and cannot move it now; the allocator frees the
466 new parameter (the unused copy destination). The client should use
467 \fBKMEM_CBRC_LATER\fR instead of \fBKMEM_CBRC_NO\fR if the object is likely to
468 become movable soon.
469 .RE
470
471 .sp
472 .ne 2
473 .na
474 \fB\fBKMEM_CBRC_DONT_NEED\fR\fR
475 .ad
476 .RS 23n
477 The client no longer needs the object; the allocator frees both the old and new
478 parameters. This response is the client's opportunity to be a model citizen and
479 give back as much as it can.
480 .RE
481
482 .sp
483 .ne 2
484 .na
485 \fB\fBKMEM_CBRC_DONT_KNOW\fR\fR
486 .ad
487 .RS 23n
488 The client does not know about the object because:
489 .sp
490 .ne 2
491 .na
492 \fBa)\fR
493 .ad
494 .RS 6n
495 the client has just allocated the object and has not yet put it wherever it
496 expects to find known objects
497 .RE
498
499 .sp
500 .ne 2
501 .na
502 \fBb)\fR
503 .ad
504 .RS 6n
505 the client has removed the object from wherever it expects to find known
506 objects and is about to free the object
507 .RE
508
509 .sp
510 .ne 2
511 .na
512 \fBc)\fR
513 .ad
514 .RS 6n
515 the client has freed the object
516 .RE
517
518 In all of these cases above, the allocator frees the new parameter (the unused
519 copy destination) and searches for the old parameter in the magazine layer. If
520 the object is found, it is removed from the magazine layer and freed to the
521 slab layer so that it will no longer tie up an entire page of memory.
522 .RE
523
524 .sp
525 .LP
526 Any object passed to the \fBmove()\fR callback is guaranteed to have been
527 touched only by the allocator or by the client. Because memory patterns applied
528 by the allocator always set at least one of the two lowest order bits, the
529 bottom two bits of any pointer member (other than \fBchar *\fR or \fBshort
530 *\fR, which may not be 8-byte aligned on all platforms) are available to the
531 client for marking cached objects that the client is about to free. This way,
532 the client can recognize known objects in the \fBmove()\fR callback by the
533 unmarked (valid) pointer value.
534 .sp
535 .LP
536 If the client refuses to move an object with either \fBKMEM_CBRC_NO\fR or
537 \fBKMEM_CBRC_LATER\fR, and that object later becomes movable, the client can
538 notify the allocator by calling \fBkmem_cache_move_notify()\fR. Alternatively,
539 the client can simply wait for the allocator to call back again with the same
540 object address. Responding \fBKMEM_CRBC_NO\fR even once or responding
541 \fBKMEM_CRBC_LATER\fR too many times for the same object makes the allocator
542 less likely to call back again for that object.
543 .LP
544 .nf
545 [Synopsis for notification function:]
546 .fi
547
548 .LP
549 .nf
550 \fBvoid\fR \fBkmem_cache_move_notify\fR(\fBkmem_cache_t\fR *\fIcp\fR, \fBvoid\fR *\fIobj\fR);
551 .fi
552
553 .sp
554 .LP
555 The parameters for the \fBnotification\fR function are as follows:
556 .sp
557 .ne 2
558 .na
559 \fB\fIcp\fR\fR
560 .ad
561 .RS 7n
562 Pointer to the object cache.
563 .RE
564
565 .sp
566 .ne 2
567 .na
568 \fB\fIobj\fR\fR
569 .ad
570 .RS 7n
571 Pointer to the object that has become movable since an earlier refusal to move
572 it.
573 .RE
574
575 .SH CONTEXT
576 Constructors can be invoked during any call to \fBkmem_cache_alloc()\fR, and
577 will run in that context. Similarly, destructors can be invoked during any call
578 to \fBkmem_cache_free()\fR, and can also be invoked during
579 \fBkmem_cache_destroy()\fR. Therefore, the functions that a constructor or
580 destructor invokes must be appropriate in that context. Furthermore, the
581 allocator may also call the constructor and destructor on objects still under
582 its control without client involvement.
583 .sp
584 .LP
585 \fBkmem_cache_create()\fR and \fBkmem_cache_destroy()\fR must not be called
586 from interrupt context. \fBkmem_cache_create()\fR can also block for available
587 memory.
588 .sp
589 .LP
590 \fBkmem_cache_alloc()\fR can be called from interrupt context only if the
591 \fBKM_NOSLEEP\fR flag is set. It can be called from user or kernel context
592 with any valid flag.
593 .sp
594 .LP
595 \fBkmem_cache_free()\fR can be called from user, kernel, or interrupt context.
596 .sp
597 .LP
598 \fBkmem_cache_set_move()\fR is called from the same context as
599 \fBkmem_cache_create()\fR, immediately after \fBkmem_cache_create()\fR and
600 before allocating any objects from the cache.
601 .sp
602 .LP
603 The registered \fBmove()\fR callback is always invoked in the same global
604 callback thread dedicated for move requests, guaranteeing that no matter how
605 many clients register a \fBmove()\fR function, the allocator never tries to
606 move more than one object at a time. Neither the allocator nor the client can
607 be assumed to know the object's whereabouts at the time of the callback.
608 .SH EXAMPLES
609 \fBExample 1 \fRObject Caching
610 .sp
611 .LP
612 Consider the following data structure:
613
614 .sp
615 .in +2
616 .nf
617 struct foo {
618 kmutex_t foo_lock;
619 kcondvar_t foo_cv;
620 struct bar *foo_barlist;
621 int foo_refcnt;
622 };
623 .fi
624 .in -2
625
626 .sp
627 .LP
628 Assume that a \fBfoo\fR structure cannot be freed until there are no
629 outstanding references to it (\fBfoo_refcnt == 0\fR) and all of its pending
630 \fBbar\fR events (whatever they are) have completed (\fBfoo_barlist ==
631 NULL\fR). The life cycle of a dynamically allocated \fBfoo\fR would be
632 something like this:
633
634 .sp
635 .in +2
636 .nf
637 foo = kmem_alloc(sizeof (struct foo), KM_SLEEP);
638 mutex_init(&foo->foo_lock, ...);
639 cv_init(&foo->foo_cv, ...);
640 foo->foo_refcnt = 0;
641 foo->foo_barlist = NULL;
642 use foo;
643 ASSERT(foo->foo_barlist == NULL);
644 ASSERT(foo->foo_refcnt == 0);
645 cv_destroy(&foo->foo_cv);
646 mutex_destroy(&foo->foo_lock);
647 kmem_free(foo);
648 .fi
649 .in -2
650
651 .sp
652 .LP
653 Notice that between each use of a \fBfoo\fR object we perform a sequence of
654 operations that constitutes nothing but expensive overhead. All of this
655 overhead (that is, everything other than \fBuse foo\fR above) can be eliminated
656 by object caching.
657
658 .sp
659 .in +2
660 .nf
661 int
662 foo_constructor(void *buf, void *arg, int tags)
663 {
664 struct foo *foo = buf;
665 mutex_init(&foo->foo_lock, ...);
666 cv_init(&foo->foo_cv, ...);
667 foo->foo_refcnt = 0;
668 foo->foo_barlist = NULL;
669 return (0);
670 }
671
672 void
673 foo_destructor(void *buf, void *arg)
674 {
675 struct foo *foo = buf;
676 ASSERT(foo->foo_barlist == NULL);
677 ASSERT(foo->foo_refcnt == 0);
678 cv_destroy(&foo->foo_cv);
679 mutex_destroy(&foo->foo_lock);
680 }
681
682 user_arg = ddi_get_soft_state(foo_softc, instance);
683 (void) snprintf(buf, KSTAT_STRLEN, "foo%d_cache",
684 ddi_get_instance(dip));
685 foo_cache = kmem_cache_create(buf,
686 sizeof (struct foo), 0,
687 foo_constructor, foo_destructor,
688 NULL, user_arg, 0);
689 .fi
690 .in -2
691
692 .sp
693 .LP
694 To allocate, use, and free a \fBfoo\fR object:
695
696 .sp
697 .in +2
698 .nf
699 foo = kmem_cache_alloc(foo_cache, KM_SLEEP);
700 use foo;
701 kmem_cache_free(foo_cache, foo);
702 .fi
703 .in -2
704
705 .sp
706 .LP
707 This makes \fBfoo\fR allocation fast, because the allocator will usually do
708 nothing more than fetch an already-constructed \fBfoo\fR from the cache.
709 \fBfoo_constructor\fR and \fBfoo_destructor\fR will be invoked only to populate
710 and drain the cache, respectively.
711
712 .LP
713 \fBExample 2 \fRRegistering a Move Callback
714 .sp
715 .LP
716 To register a \fBmove()\fR callback:
717
718 .sp
719 .in +2
720 .nf
721 object_cache = kmem_cache_create(...);
722 kmem_cache_set_move(object_cache, object_move);
723 .fi
724 .in -2
725
726 .SH RETURN VALUES
727 If successful, the constructor function must return \fB0\fR. If
728 \fBKM_NOSLEEP\fR or \fBKM_NOSLEEP_LAZY\fR is set and memory cannot be
729 allocated without sleeping, the constructor must return -\fB1\fR. If the
730 constructor takes extraordinary steps during a \fBKM_NOSLEEP\fR construction,
731 it may not take those for a \fBKM_NOSLEEP_LAZY\fR construction.
732 .sp
733 .LP
734 \fBkmem_cache_create()\fR returns a pointer to the allocated cache.
735 .sp
736 .LP
737 If successful, \fBkmem_cache_alloc()\fR returns a pointer to the allocated
738 object. If \fBKM_NOSLEEP\fR is set and memory cannot be allocated without
739 sleeping, \fBkmem_cache_alloc()\fR returns \fBNULL\fR.
740 .SH ATTRIBUTES
741 See \fBattributes\fR(5) for descriptions of the following attributes:
742 .sp
743
744 .sp
745 .TS
746 box;
747 c | c
748 l | l .
749 ATTRIBUTE TYPE ATTRIBUTE VALUE
750 _
751 Interface Stability Committed
752 .TE
753
754 .SH SEE ALSO
755 \fBcondvar\fR(9F), \fBkmem_alloc\fR(9F), \fBmutex\fR(9F), \fBkstat\fR(9S)
756 .sp
757 .LP
758 \fIWriting Device Drivers\fR
759 .sp
760 .LP
761 \fIThe Slab Allocator: An Object-Caching Kernel Memory Allocator\fR, Bonwick,
762 J.; USENIX Summer 1994 Technical Conference (1994).
763 .sp
764 .LP
765 \fIMagazines and vmem: Extending the Slab Allocator to Many CPUs and Arbitrary
766 Resources\fR, Bonwick, J. and Adams, J.; USENIX 2001 Technical Conference
767 (2001).
768 .SH NOTES
769 The constructor must be immediately reversible by the destructor, since the
770 allocator may call the constructor and destructor on objects still under its
771 control at any time without client involvement.
772 .sp
773 .LP
774 The constructor must respect the \fIkmflags\fR argument by forwarding it to
775 allocations made inside the \fIconstructor\fR, and must not ASSERT anything
776 about the given flags.
777 .sp
778 .LP
779 The user argument forwarded to the constructor must be fully operational before
780 it is passed to \fBkmem_cache_create()\fR.