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