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