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