1 /* 2 * Copyright (c) Facebook, Inc. 3 * All rights reserved. 4 * 5 * This source code is licensed under both the BSD-style license (found in the 6 * LICENSE file in the root directory of this source tree) and the GPLv2 (found 7 * in the COPYING file in the root directory of this source tree). 8 * You may select, at your option, one of the above-listed licenses. 9 */ 10 11 #ifndef ZSTD_TRACE_H 12 #define ZSTD_TRACE_H 13 14 #if defined (__cplusplus) 15 extern "C" { 16 #endif 17 18 #include <stddef.h> 19 20 /* weak symbol support 21 * For now, enable conservatively: 22 * - Only GNUC 23 * - Only ELF 24 * - Only x86-64 and i386 25 * Also, explicitly disable on platforms known not to work so they aren't 26 * forgotten in the future. 27 */ 28 #if !defined(ZSTD_HAVE_WEAK_SYMBOLS) && \ 29 defined(__GNUC__) && defined(__ELF__) && \ 30 (defined(__x86_64__) || defined(_M_X64) || defined(__i386__) || defined(_M_IX86)) && \ 31 !defined(__APPLE__) && !defined(_WIN32) && !defined(__MINGW32__) && \ 32 !defined(__CYGWIN__) && !defined(_AIX) 33 # define ZSTD_HAVE_WEAK_SYMBOLS 1 34 #else 35 # define ZSTD_HAVE_WEAK_SYMBOLS 0 36 #endif 37 #if ZSTD_HAVE_WEAK_SYMBOLS 38 # define ZSTD_WEAK_ATTR __attribute__((__weak__)) 39 #else 40 # define ZSTD_WEAK_ATTR 41 #endif 42 43 /* Only enable tracing when weak symbols are available. */ 44 #ifndef ZSTD_TRACE 45 # define ZSTD_TRACE ZSTD_HAVE_WEAK_SYMBOLS 46 #endif 47 48 #if ZSTD_TRACE 49 50 struct ZSTD_CCtx_s; 51 struct ZSTD_DCtx_s; 52 struct ZSTD_CCtx_params_s; 53 54 typedef struct { 55 /** 56 * ZSTD_VERSION_NUMBER 57 * 58 * This is guaranteed to be the first member of ZSTD_trace. 59 * Otherwise, this struct is not stable between versions. If 60 * the version number does not match your expectation, you 61 * should not interpret the rest of the struct. 62 */ 63 unsigned version; 64 /** 65 * Non-zero if streaming (de)compression is used. 66 */ 67 unsigned streaming; 68 /** 69 * The dictionary ID. 70 */ 71 unsigned dictionaryID; 72 /** 73 * Is the dictionary cold? 74 * Only set on decompression. 75 */ 76 unsigned dictionaryIsCold; 77 /** 78 * The dictionary size or zero if no dictionary. 79 */ 80 size_t dictionarySize; 81 /** 82 * The uncompressed size of the data. 83 */ 84 size_t uncompressedSize; 85 /** 86 * The compressed size of the data. 87 */ 88 size_t compressedSize; 89 /** 90 * The fully resolved CCtx parameters (NULL on decompression). 91 */ 92 struct ZSTD_CCtx_params_s const* params; 93 /** 94 * The ZSTD_CCtx pointer (NULL on decompression). 95 */ 96 struct ZSTD_CCtx_s const* cctx; 97 /** 98 * The ZSTD_DCtx pointer (NULL on compression). 99 */ 100 struct ZSTD_DCtx_s const* dctx; 101 } ZSTD_Trace; 102 103 /** 104 * A tracing context. It must be 0 when tracing is disabled. 105 * Otherwise, any non-zero value returned by a tracing begin() 106 * function is presented to any subsequent calls to end(). 107 * 108 * Any non-zero value is treated as tracing is enabled and not 109 * interpreted by the library. 110 * 111 * Two possible uses are: 112 * * A timestamp for when the begin() function was called. 113 * * A unique key identifying the (de)compression, like the 114 * address of the [dc]ctx pointer if you need to track 115 * more information than just a timestamp. 116 */ 117 typedef unsigned long long ZSTD_TraceCtx; 118 119 /** 120 * Trace the beginning of a compression call. 121 * @param cctx The dctx pointer for the compression. 122 * It can be used as a key to map begin() to end(). 123 * @returns Non-zero if tracing is enabled. The return value is 124 * passed to ZSTD_trace_compress_end(). 125 */ 126 ZSTD_WEAK_ATTR ZSTD_TraceCtx ZSTD_trace_compress_begin( 127 struct ZSTD_CCtx_s const* cctx); 128 129 /** 130 * Trace the end of a compression call. 131 * @param ctx The return value of ZSTD_trace_compress_begin(). 132 * @param trace The zstd tracing info. 133 */ 134 ZSTD_WEAK_ATTR void ZSTD_trace_compress_end( 135 ZSTD_TraceCtx ctx, 136 ZSTD_Trace const* trace); 137 138 /** 139 * Trace the beginning of a decompression call. 140 * @param dctx The dctx pointer for the decompression. 141 * It can be used as a key to map begin() to end(). 142 * @returns Non-zero if tracing is enabled. The return value is 143 * passed to ZSTD_trace_compress_end(). 144 */ 145 ZSTD_WEAK_ATTR ZSTD_TraceCtx ZSTD_trace_decompress_begin( 146 struct ZSTD_DCtx_s const* dctx); 147 148 /** 149 * Trace the end of a decompression call. 150 * @param ctx The return value of ZSTD_trace_decompress_begin(). 151 * @param trace The zstd tracing info. 152 */ 153 ZSTD_WEAK_ATTR void ZSTD_trace_decompress_end( 154 ZSTD_TraceCtx ctx, 155 ZSTD_Trace const* trace); 156 157 #endif /* ZSTD_TRACE */ 158 159 #if defined (__cplusplus) 160 } 161 #endif 162 163 #endif /* ZSTD_TRACE_H */ 164