object_pool.h 4.24 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

gejun's avatar
gejun committed
18 19 20 21
// bthread - A M:N threading library to make applications more concurrent.

// Date: Sun Jul 13 15:04:18 CST 2014

22 23
#ifndef BUTIL_OBJECT_POOL_H
#define BUTIL_OBJECT_POOL_H
gejun's avatar
gejun committed
24 25 26

#include <cstddef>                       // size_t

gejun's avatar
gejun committed
27 28
// ObjectPool is a derivative class of ResourcePool to allocate and
// reuse fixed-size objects without identifiers.
gejun's avatar
gejun committed
29

30
namespace butil {
gejun's avatar
gejun committed
31 32

// Specialize following classes to override default parameters for type T.
33
//   namespace butil {
gejun's avatar
gejun committed
34
//     template <> struct ObjectPoolBlockMaxSize<Foo> {
gejun's avatar
gejun committed
35
//       static const size_t value = 1024;
gejun's avatar
gejun committed
36 37
//     };
//   }
gejun's avatar
gejun committed
38

gejun's avatar
gejun committed
39 40 41
// Memory is allocated in blocks, memory size of a block will not exceed:
//   min(ObjectPoolBlockMaxSize<T>::value,
//       ObjectPoolBlockMaxItem<T>::value * sizeof(T))
gejun's avatar
gejun committed
42
template <typename T> struct ObjectPoolBlockMaxSize {
gejun's avatar
gejun committed
43
    static const size_t value = 64 * 1024; // bytes
gejun's avatar
gejun committed
44 45
};
template <typename T> struct ObjectPoolBlockMaxItem {
gejun's avatar
gejun committed
46
    static const size_t value = 256;
gejun's avatar
gejun committed
47 48
};

gejun's avatar
gejun committed
49 50
// Free objects of each thread are grouped into a chunk before they are merged
// to the global list. Memory size of objects in one free chunk will not exceed:
yeting's avatar
yeting committed
51
//   min(ObjectPoolFreeChunkMaxItem<T>::value() * sizeof(T),
gejun's avatar
gejun committed
52 53
//       ObjectPoolBlockMaxSize<T>::value,
//       ObjectPoolBlockMaxItem<T>::value * sizeof(T))
gejun's avatar
gejun committed
54
template <typename T> struct ObjectPoolFreeChunkMaxItem {
gejun's avatar
gejun committed
55
    static size_t value() { return 256; }
gejun's avatar
gejun committed
56 57 58 59 60 61 62 63 64 65
};

// ObjectPool calls this function on newly constructed objects. If this
// function returns false, the object is destructed immediately and
// get_object() shall return NULL. This is useful when the constructor
// failed internally(namely ENOMEM).
template <typename T> struct ObjectPoolValidator {
    static bool validate(const T*) { return true; }
};

66
}  // namespace butil
gejun's avatar
gejun committed
67

68
#include "butil/object_pool_inl.h"
gejun's avatar
gejun committed
69

70
namespace butil {
gejun's avatar
gejun committed
71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112

// Get an object typed |T|. The object should be cleared before usage.
// NOTE: T must be default-constructible.
template <typename T> inline T* get_object() {
    return ObjectPool<T>::singleton()->get_object();
}

// Get an object whose constructor is T(arg1)
template <typename T, typename A1>
inline T* get_object(const A1& arg1) {
    return ObjectPool<T>::singleton()->get_object(arg1);
}

// Get an object whose constructor is T(arg1, arg2)
template <typename T, typename A1, typename A2>
inline T* get_object(const A1& arg1, const A2& arg2) {
    return ObjectPool<T>::singleton()->get_object(arg1, arg2);
}

// Return the object |ptr| back. The object is NOT destructed and will be
// returned by later get_object<T>. Similar with free/delete, validity of
// the object is not checked, user shall not return a not-yet-allocated or
// already-returned object otherwise behavior is undefined.
// Returns 0 when successful, -1 otherwise.
template <typename T> inline int return_object(T* ptr) {
    return ObjectPool<T>::singleton()->return_object(ptr);
}

// Reclaim all allocated objects typed T if caller is the last thread called
// this function, otherwise do nothing. You rarely need to call this function
// manually because it's called automatically when each thread quits.
template <typename T> inline void clear_objects() {
    ObjectPool<T>::singleton()->clear_objects();
}

// Get description of objects typed T.
// This function is possibly slow because it iterates internal structures.
// Don't use it frequently like a "getter" function.
template <typename T> ObjectPoolInfo describe_objects() {
    return ObjectPool<T>::singleton()->describe_objects();
}

113
}  // namespace butil
gejun's avatar
gejun committed
114

115
#endif  // BUTIL_OBJECT_POOL_H