1
2/*
3 * Copyright 2006 The Android Open Source Project
4 *
5 * Use of this source code is governed by a BSD-style license that can be
6 * found in the LICENSE file.
7 */
8
9
10#ifndef SkTemplates_DEFINED
11#define SkTemplates_DEFINED
12
13#include "SkTypes.h"
14#include <new>
15
16/** \file SkTemplates.h
17
18    This file contains light-weight template classes for type-safe and exception-safe
19    resource management.
20*/
21
22/**
23 *  Marks a local variable as known to be unused (to avoid warnings).
24 *  Note that this does *not* prevent the local variable from being optimized away.
25 */
26template<typename T> inline void sk_ignore_unused_variable(const T&) { }
27
28/**
29 *  SkTIsConst<T>::value is true if the type T is const.
30 *  The type T is constrained not to be an array or reference type.
31 */
32template <typename T> struct SkTIsConst {
33    static T* t;
34    static uint16_t test(const volatile void*);
35    static uint32_t test(volatile void *);
36    static const bool value = (sizeof(uint16_t) == sizeof(test(t)));
37};
38
39///@{
40/** SkTConstType<T, CONST>::type will be 'const T' if CONST is true, 'T' otherwise. */
41template <typename T, bool CONST> struct SkTConstType {
42    typedef T type;
43};
44template <typename T> struct SkTConstType<T, true> {
45    typedef const T type;
46};
47///@}
48
49/**
50 *  Returns a pointer to a D which comes immediately after S[count].
51 */
52template <typename D, typename S> static D* SkTAfter(S* ptr, size_t count = 1) {
53    return reinterpret_cast<D*>(ptr + count);
54}
55
56/**
57 *  Returns a pointer to a D which comes byteOffset bytes after S.
58 */
59template <typename D, typename S> static D* SkTAddOffset(S* ptr, size_t byteOffset) {
60    // The intermediate char* has the same const-ness as D as this produces better error messages.
61    // This relies on the fact that reinterpret_cast can add constness, but cannot remove it.
62    return reinterpret_cast<D*>(
63        reinterpret_cast<typename SkTConstType<char, SkTIsConst<D>::value>::type*>(ptr) + byteOffset
64    );
65}
66
67/** \class SkAutoTCallVProc
68
69    Call a function when this goes out of scope. The template uses two
70    parameters, the object, and a function that is to be called in the destructor.
71    If detach() is called, the object reference is set to null. If the object
72    reference is null when the destructor is called, we do not call the
73    function.
74*/
75template <typename T, void (*P)(T*)> class SkAutoTCallVProc : SkNoncopyable {
76public:
77    SkAutoTCallVProc(T* obj): fObj(obj) {}
78    ~SkAutoTCallVProc() { if (fObj) P(fObj); }
79    T* detach() { T* obj = fObj; fObj = NULL; return obj; }
80private:
81    T* fObj;
82};
83
84/** \class SkAutoTCallIProc
85
86Call a function when this goes out of scope. The template uses two
87parameters, the object, and a function that is to be called in the destructor.
88If detach() is called, the object reference is set to null. If the object
89reference is null when the destructor is called, we do not call the
90function.
91*/
92template <typename T, int (*P)(T*)> class SkAutoTCallIProc : SkNoncopyable {
93public:
94    SkAutoTCallIProc(T* obj): fObj(obj) {}
95    ~SkAutoTCallIProc() { if (fObj) P(fObj); }
96    T* detach() { T* obj = fObj; fObj = NULL; return obj; }
97private:
98    T* fObj;
99};
100
101/** \class SkAutoTDelete
102  An SkAutoTDelete<T> is like a T*, except that the destructor of SkAutoTDelete<T>
103  automatically deletes the pointer it holds (if any).  That is, SkAutoTDelete<T>
104  owns the T object that it points to.  Like a T*, an SkAutoTDelete<T> may hold
105  either NULL or a pointer to a T object.  Also like T*, SkAutoTDelete<T> is
106  thread-compatible, and once you dereference it, you get the threadsafety
107  guarantees of T.
108
109  The size of a SkAutoTDelete is small: sizeof(SkAutoTDelete<T>) == sizeof(T*)
110*/
111template <typename T> class SkAutoTDelete : SkNoncopyable {
112public:
113    SkAutoTDelete(T* obj = NULL) : fObj(obj) {}
114    ~SkAutoTDelete() { SkDELETE(fObj); }
115
116    T* get() const { return fObj; }
117    T& operator*() const { SkASSERT(fObj); return *fObj; }
118    T* operator->() const { SkASSERT(fObj); return fObj; }
119
120    void reset(T* obj) {
121        if (fObj != obj) {
122            SkDELETE(fObj);
123            fObj = obj;
124        }
125    }
126
127    /**
128     *  Delete the owned object, setting the internal pointer to NULL.
129     */
130    void free() {
131        SkDELETE(fObj);
132        fObj = NULL;
133    }
134
135    /**
136     *  Transfer ownership of the object to the caller, setting the internal
137     *  pointer to NULL. Note that this differs from get(), which also returns
138     *  the pointer, but it does not transfer ownership.
139     */
140    T* detach() {
141        T* obj = fObj;
142        fObj = NULL;
143        return obj;
144    }
145
146private:
147    T*  fObj;
148};
149
150// Calls ~T() in the destructor.
151template <typename T> class SkAutoTDestroy : SkNoncopyable {
152public:
153    SkAutoTDestroy(T* obj = NULL) : fObj(obj) {}
154    ~SkAutoTDestroy() {
155        if (NULL != fObj) {
156            fObj->~T();
157        }
158    }
159
160    T* get() const { return fObj; }
161    T& operator*() const { SkASSERT(fObj); return *fObj; }
162    T* operator->() const { SkASSERT(fObj); return fObj; }
163
164private:
165    T*  fObj;
166};
167
168template <typename T> class SkAutoTDeleteArray : SkNoncopyable {
169public:
170    SkAutoTDeleteArray(T array[]) : fArray(array) {}
171    ~SkAutoTDeleteArray() { SkDELETE_ARRAY(fArray); }
172
173    T*      get() const { return fArray; }
174    void    free() { SkDELETE_ARRAY(fArray); fArray = NULL; }
175    T*      detach() { T* array = fArray; fArray = NULL; return array; }
176
177private:
178    T*  fArray;
179};
180
181/** Allocate an array of T elements, and free the array in the destructor
182 */
183template <typename T> class SkAutoTArray : SkNoncopyable {
184public:
185    SkAutoTArray() {
186        fArray = NULL;
187        SkDEBUGCODE(fCount = 0;)
188    }
189    /** Allocate count number of T elements
190     */
191    explicit SkAutoTArray(int count) {
192        SkASSERT(count >= 0);
193        fArray = NULL;
194        if (count) {
195            fArray = SkNEW_ARRAY(T, count);
196        }
197        SkDEBUGCODE(fCount = count;)
198    }
199
200    /** Reallocates given a new count. Reallocation occurs even if new count equals old count.
201     */
202    void reset(int count) {
203        SkDELETE_ARRAY(fArray);
204        SkASSERT(count >= 0);
205        fArray = NULL;
206        if (count) {
207            fArray = SkNEW_ARRAY(T, count);
208        }
209        SkDEBUGCODE(fCount = count;)
210    }
211
212    ~SkAutoTArray() {
213        SkDELETE_ARRAY(fArray);
214    }
215
216    /** Return the array of T elements. Will be NULL if count == 0
217     */
218    T* get() const { return fArray; }
219
220    /** Return the nth element in the array
221     */
222    T&  operator[](int index) const {
223        SkASSERT((unsigned)index < (unsigned)fCount);
224        return fArray[index];
225    }
226
227private:
228    T*  fArray;
229    SkDEBUGCODE(int fCount;)
230};
231
232/** Wraps SkAutoTArray, with room for up to N elements preallocated
233 */
234template <int N, typename T> class SkAutoSTArray : SkNoncopyable {
235public:
236    /** Initialize with no objects */
237    SkAutoSTArray() {
238        fArray = NULL;
239        fCount = 0;
240    }
241
242    /** Allocate count number of T elements
243     */
244    SkAutoSTArray(int count) {
245        fArray = NULL;
246        fCount = 0;
247        this->reset(count);
248    }
249
250    ~SkAutoSTArray() {
251        this->reset(0);
252    }
253
254    /** Destroys previous objects in the array and default constructs count number of objects */
255    void reset(int count) {
256        T* start = fArray;
257        T* iter = start + fCount;
258        while (iter > start) {
259            (--iter)->~T();
260        }
261
262        if (fCount != count) {
263            if (fCount > N) {
264                // 'fArray' was allocated last time so free it now
265                SkASSERT((T*) fStorage != fArray);
266                sk_free(fArray);
267            }
268
269            if (count > N) {
270                fArray = (T*) sk_malloc_throw(count * sizeof(T));
271            } else if (count > 0) {
272                fArray = (T*) fStorage;
273            } else {
274                fArray = NULL;
275            }
276
277            fCount = count;
278        }
279
280        iter = fArray;
281        T* stop = fArray + count;
282        while (iter < stop) {
283            SkNEW_PLACEMENT(iter++, T);
284        }
285    }
286
287    /** Return the number of T elements in the array
288     */
289    int count() const { return fCount; }
290
291    /** Return the array of T elements. Will be NULL if count == 0
292     */
293    T* get() const { return fArray; }
294
295    /** Return the nth element in the array
296     */
297    T&  operator[](int index) const {
298        SkASSERT(index < fCount);
299        return fArray[index];
300    }
301
302private:
303    int     fCount;
304    T*      fArray;
305    // since we come right after fArray, fStorage should be properly aligned
306    char    fStorage[N * sizeof(T)];
307};
308
309/** Manages an array of T elements, freeing the array in the destructor.
310 *  Does NOT call any constructors/destructors on T (T must be POD).
311 */
312template <typename T> class SkAutoTMalloc : SkNoncopyable {
313public:
314    /** Takes ownership of the ptr. The ptr must be a value which can be passed to sk_free. */
315    explicit SkAutoTMalloc(T* ptr = NULL) {
316        fPtr = ptr;
317    }
318
319    /** Allocates space for 'count' Ts. */
320    explicit SkAutoTMalloc(size_t count) {
321        fPtr = (T*)sk_malloc_flags(count * sizeof(T), SK_MALLOC_THROW | SK_MALLOC_TEMP);
322    }
323
324    ~SkAutoTMalloc() {
325        sk_free(fPtr);
326    }
327
328    /** Resize the memory area pointed to by the current ptr preserving contents. */
329    void realloc(size_t count) {
330        fPtr = reinterpret_cast<T*>(sk_realloc_throw(fPtr, count * sizeof(T)));
331    }
332
333    /** Resize the memory area pointed to by the current ptr without preserving contents. */
334    void reset(size_t count) {
335        sk_free(fPtr);
336        fPtr = (T*)sk_malloc_flags(count * sizeof(T), SK_MALLOC_THROW | SK_MALLOC_TEMP);
337    }
338
339    T* get() const { return fPtr; }
340
341    operator T*() {
342        return fPtr;
343    }
344
345    operator const T*() const {
346        return fPtr;
347    }
348
349    T& operator[](int index) {
350        return fPtr[index];
351    }
352
353    const T& operator[](int index) const {
354        return fPtr[index];
355    }
356
357    /**
358     *  Transfer ownership of the ptr to the caller, setting the internal
359     *  pointer to NULL. Note that this differs from get(), which also returns
360     *  the pointer, but it does not transfer ownership.
361     */
362    T* detach() {
363        T* ptr = fPtr;
364        fPtr = NULL;
365        return ptr;
366    }
367
368private:
369    T* fPtr;
370};
371
372template <size_t N, typename T> class SkAutoSTMalloc : SkNoncopyable {
373public:
374    SkAutoSTMalloc() {
375        fPtr = NULL;
376    }
377
378    SkAutoSTMalloc(size_t count) {
379        if (count > N) {
380            fPtr = (T*)sk_malloc_flags(count * sizeof(T), SK_MALLOC_THROW | SK_MALLOC_TEMP);
381        } else if (count) {
382            fPtr = fTStorage;
383        } else {
384            fPtr = NULL;
385        }
386    }
387
388    ~SkAutoSTMalloc() {
389        if (fPtr != fTStorage) {
390            sk_free(fPtr);
391        }
392    }
393
394    // doesn't preserve contents
395    T* reset(size_t count) {
396        if (fPtr != fTStorage) {
397            sk_free(fPtr);
398        }
399        if (count > N) {
400            fPtr = (T*)sk_malloc_flags(count * sizeof(T), SK_MALLOC_THROW | SK_MALLOC_TEMP);
401        } else if (count) {
402            fPtr = fTStorage;
403        } else {
404            fPtr = NULL;
405        }
406        return fPtr;
407    }
408
409    T* get() const { return fPtr; }
410
411    operator T*() {
412        return fPtr;
413    }
414
415    operator const T*() const {
416        return fPtr;
417    }
418
419    T& operator[](int index) {
420        return fPtr[index];
421    }
422
423    const T& operator[](int index) const {
424        return fPtr[index];
425    }
426
427private:
428    T*          fPtr;
429    union {
430        uint32_t    fStorage32[(N*sizeof(T) + 3) >> 2];
431        T           fTStorage[1];   // do NOT want to invoke T::T()
432    };
433};
434
435/**
436 * Reserves memory that is aligned on double and pointer boundaries.
437 * Hopefully this is sufficient for all practical purposes.
438 */
439template <size_t N> class SkAlignedSStorage : SkNoncopyable {
440public:
441    void* get() { return fData; }
442private:
443    union {
444        void*   fPtr;
445        double  fDouble;
446        char    fData[N];
447    };
448};
449
450/**
451 * Reserves memory that is aligned on double and pointer boundaries.
452 * Hopefully this is sufficient for all practical purposes. Otherwise,
453 * we have to do some arcane trickery to determine alignment of non-POD
454 * types. Lifetime of the memory is the lifetime of the object.
455 */
456template <int N, typename T> class SkAlignedSTStorage : SkNoncopyable {
457public:
458    /**
459     * Returns void* because this object does not initialize the
460     * memory. Use placement new for types that require a cons.
461     */
462    void* get() { return fStorage.get(); }
463private:
464    SkAlignedSStorage<sizeof(T)*N> fStorage;
465};
466
467#endif
468