Skip to content

Commit e58f2a6

Browse files
johnezangjohnezang
committed
Initial push of JSONKit v1.4. May not be the final v1.4 commit. See CHANGELOG.md for info. The biggest news is JSONKit is anywhere from 30% to 60% faster than JSONKit v1.3 for reading / parsing JSON!
1 parent b612564 commit e58f2a6

File tree

4 files changed

+1020
-539
lines changed

4 files changed

+1020
-539
lines changed

‎CHANGELOG.md

Lines changed: 95 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,83 @@
11
# JSONKit Changelog
22

3-
## Version 1.3 2011/05/04
3+
## Version 1.4 2011/28/02
4+
5+
### Bug Fixes
6+
7+
* JSONKit has a fast and a slow path for parsing JSON Strings. The slow path is needed whenever special string processing is required, such as the conversion of `\` escape sequences or ill-formed UTF-8. Although the slow path had a check for characters < `0x20`, which are not permitted by the [RFC 4627][], there was a bug such that the condition was never actually checked. As a result, JSONKit would have incorrectly accepted JSON that contained characters < `0x20` if it was using the slow path to process a JSON String.
8+
* The low surrogate in a <code>\u<i><b>high</b></i>\u<i><b>low</b></i></code> escape sequence in a JSON String was incorrectly treating `dfff` as ill-formed Unicode. This was due to a comparison that used `>= 0xdfff` instead of `> 0xdfff` as it should have.
9+
* `JKParseOptionLooseUnicode` was not properly honored when parsing some types of ill-formed Unicode in <code>\u<i><b>HHHH</b></i></code> escapes in JSON Strings.
10+
11+
### Important Changes
12+
13+
* The `JK_ENABLE_CF_TRANSFER_OWNERSHIP_CALLBACKS` pre-processor define flag that was added to JSONKit v1.3 has been removed.
14+
15+
`JK_ENABLE_CF_TRANSFER_OWNERSHIP_CALLBACKS` was added in JSONKit v1.3 as a temporary work around. While the author was aware of other ways to fix the particular problem caused by the usage of "transfer of ownership callbacks" with Core Foundation classes, the fix provided in JSONKit v1.3 was trivial to implement. This allowed people who needed that functionality to use JSONKit while a proper solution to the problem was worked on. JSONKit v1.4 is the result of that work.
16+
17+
JSONKit v1.4 no longer uses the Core Foundation collection classes [`CFArray`][CFArray] and [`CFDictionary`][CFDictionary]. Instead, JSONKit v1.4 contains a concrete subclass of [`NSArray`][NSArray] and [`NSDictionary`][NSDictionary]&ndash; `JKArray` and `JKDictionary`, respectively. As a result, JSONKit has complete control over the behavior of how items are added and managed within an instantiated collection object. The `JKArray` and `JKDictionary` classes are private to JSONKit, you should not instantiate them direction. Since they are concrete subclasses of their respective collection class cluster, they behave and act exactly the same as [`NSArray`][NSArray] and [`NSDictionary`][NSDictionary].
18+
19+
The first benefit is that the "transfer of ownership" object ownership policy can now be safely used. Because the JSONKit collection objects understand that some methods, such as [`-mutableCopy`][-mutableCopy], should not inherit the same "transfer of ownership" object ownership policy, but must follow the standard Cocoa object ownership policy. The "transfer of ownership" object ownership policy reduces the number of [`-retain`][-retain] and [`-release`][-release] calls needed to add an object to a collection, and when creating a large number of objects very quickly (as you would expect when parsing JSON), this can result in a non-trivial amount of time. Eliminating these calls means faster JSON parsing.
20+
21+
A second benefit is that the author encountered some unexpected behavior when using the [`CFDictionaryCreate`][CFDictionaryCreate] function to create a dictionary and the `keys` argument contained duplicate keys. This required JSONKit to de-duplicate the keys and values before calling [`CFDictionaryCreate`][CFDictionaryCreate]. Unfortunately, JSONKit always had to scan all the keys to make sure there were no duplicates, even though 99.99% of the time there were none. This was less than optimal, particularly because one of the solutions to this particular problem is to use a hash table to perform the de-duplication. Now JSONKit can do the de-duplication while it is instantiating the dictionary collection, solving two problems at once.
22+
23+
Yet another benefit is that the recently instantiated object cache that JSONKit uses can be used to cache information about the keys used to create dictionary collections, in particular a keys [`-hash`][-hash] value. For a lot of real world JSON, this effectively means that the [`-hash`][-hash] for a key is calculated once, and that value is reused again and again when creating dictionaries. Because all the information required to create the hash table used by `JKDictionary` is already determined at the time the `JKDictionary` object is instantiated, populating the `JKDictionary` is now a very tight loop that only has to call [`-isEqual:`][-isEqual:] on the rare occasions that the JSON being parsed contains duplicate keys. Since the functions that handle this logic are all declared `static` and are internal to JSONKit, the compiler can heavily optimize this code.
24+
25+
What does this mean in terms of performance? JSONKit was already fast, but now, it's even faster. Below is some benchmark times for [`twitter_public_timeline.json`][twitter_public_timeline.json] in [samsoffes / json-benchmarks](https://github.com/samsoffes/json-benchmarks), where _read_ means to convert the JSON to native Objective-C objects, and _write_ means to convert the native Objective-C to JSON&mdash;
26+
27+
<pre>
28+
v1.3 read : min: 456.000 us, avg: 460.056 us, char/s: 53341332.36 / 50.870 MB/s
29+
v1.3 write: min: 150.000 us, avg: 151.816 us, char/s: 161643041.58 / 154.155 MB/s</pre>
30+
31+
<pre>
32+
v1.4 read : min: 285.000 us, avg: 288.603 us, char/s: 85030301.14 / 81.091 MB/s
33+
v1.4 write: min: 127.000 us, avg: 129.617 us, char/s: 189327017.29 / 180.556 MB/s</pre>
34+
35+
JSONKit v1.4 is nearly 60% faster at reading and 17% faster at writing than v1.3.
36+
37+
The following is the JSON test file taken from the project available at [this blog post](http://psionides.jogger.pl/2010/12/12/cocoa-json-parsing-libraries-part-2/). The keys and information contained in the JSON was anonymized with random characters. Since JSONKit relies on its recently instantiated object cache for a lot of its performance, this JSON happens to be "the worst corner case possible".
38+
39+
<pre>
40+
v1.3 read : min: 5222.000 us, avg: 5262.344 us, char/s: 15585260.10 / 14.863 MB/s
41+
v1.3 write: min: 1253.000 us, avg: 1259.914 us, char/s: 65095712.88 / 62.080 MB/s</pre>
42+
43+
<pre>
44+
v1.4 read : min: 4096.000 us, avg: 4122.240 us, char/s: 19895736.30 / 18.974 MB/s
45+
v1.4 write: min: 1319.000 us, avg: 1335.538 us, char/s: 61409709.05 / 58.565 MB/s</pre>
46+
47+
JSONKit v1.4 is 28% faster at reading and 6% faster at writing that v1.3 in this worst-case torture test.
48+
49+
While your milage may vary, you will likely see improvements in the 50% for reading and 10% for writing on your real world JSON. The nature of JSONKits cache means performance improvements is statistical in nature and depends on the particular properties of the JSON being parsed.
50+
51+
For comparison, [json-framework][], a popular Objective-C JSON parsing library, turns in the following benchmark times for [`twitter_public_timeline.json`][twitter_public_timeline.json]&mdash;
52+
53+
<pre>
54+
read : min: 1670.000 us, avg: 1682.461 us, char/s: 14585776.43 / 13.910 MB/s
55+
write: min: 1021.000 us, avg: 1028.970 us, char/s: 23849091.81 / 22.744 MB/s</pre>
56+
57+
Since the benchmark for JSONKit and [json-framework][] was done on the same computer, it's safe to compare the timing results. The version of [json-framework][] used was the latest v3.0 available via the master branch at the time of this writing on github.com.
58+
59+
JSONKit v1.4 is 483% faster at reading and 694% faster at writing than [json-framework][].
60+
61+
### Important Notes
62+
63+
* JSONKit v1.4 now uses custom concrete subclasses of [`NSArray`][NSArray] and [`NSDictionary`][NSDictionary].
64+
65+
In theory, these custom classes should behave exactly the same as the respective Foundation / Cocoa counterparts.
66+
67+
As usual, in practice may have non-linear excursions from what theory predicts. It is also virtually impossible to properly test or predict how these custom classes will interact with software in the wild.
68+
69+
Most likely, if you do encounter a problem, it will happen very quickly, and you should report a bug via the [github.com JSONKit Issue Tracker][bugtracker].
70+
71+
72+
### Other Changes
73+
74+
* Added a `__clang_analyzer__` pre-processor conditional around some code that the `clang` static analyzer was giving false positives for. However, `clang` versions &le; 1.5 do not define `__clang_analyzer__` and therefore will continue to emit analyzer warnings.
75+
* The cache now uses a linear congruential generator to select which item in the cache to randomly age. This should age items in the cache more fairly.
76+
* Removed a lot of internal and private data structures from `JSONKit.h` and put them in `JSONKit.m`.
77+
* Modified the way floating point values are serialized. Previously, the [`printf`][printf] format conversion `%.16g` was used. This was changed to `%.17g` which should theoretically allow for up to a full `float`, or [IEEE 754 Single 32-bit floating-point][Single Precision], of precision when converting floating point values to decimal representation.
78+
* The usual sundry of inconsequential tidies and what not, such as updating the README.md, etc.
79+
80+
## Version 1.3 2011/05/02
481

582
### New Features
683

@@ -57,13 +134,27 @@
57134

58135
No change log information was kept for versions prior to 1.2.
59136

137+
[bugtracker]: https://github.com/johnezang/JSONKit/issues
138+
[RFC 4627]: http://tools.ietf.org/html/rfc4627
139+
[twitter_public_timeline.json]: https://github.com/samsoffes/json-benchmarks/blob/master/Resources/twitter_public_timeline.json
140+
[json-framework]: https://github.com/stig/json-framework
141+
[Single Precision]: http://en.wikipedia.org/wiki/Single_precision
60142
[kCFTypeArrayCallBacks]: http://developer.apple.com/library/mac/documentation/CoreFoundation/Reference/CFArrayRef/Reference/reference.html#//apple_ref/c/data/kCFTypeArrayCallBacks
61143
[kCFTypeDictionaryKeyCallBacks]: http://developer.apple.com/library/mac/documentation/CoreFoundation/Reference/CFDictionaryRef/Reference/reference.html#//apple_ref/c/data/kCFTypeDictionaryKeyCallBacks
62144
[kCFTypeDictionaryValueCallBacks]: http://developer.apple.com/library/mac/documentation/CoreFoundation/Reference/CFDictionaryRef/Reference/reference.html#//apple_ref/c/data/kCFTypeDictionaryValueCallBacks
63-
[-mutableCopy]: http://developer.apple.com/library/mac/#documentation/Cocoa/Reference/Foundation/Classes/NSObject_Class/Reference/Reference.html%23//apple_ref/occ/instm/NSObject/mutableCopy
64-
[-copy]: http://developer.apple.com/library/mac/#documentation/Cocoa/Reference/Foundation/Classes/NSObject_Class/Reference/Reference.html%23//apple_ref/occ/instm/NSObject/copy
65-
[-retain]: http://developer.apple.com/library/mac/documentation/Cocoa/Reference/Foundation/Protocols/NSObject_Protocol/Reference/NSObject.html#//apple_ref/occ/intfm/NSObject/retain
66145
[CFRetain]: http://developer.apple.com/library/mac/documentation/CoreFoundation/Reference/CFTypeRef/Reference/reference.html#//apple_ref/c/func/CFRetain
67146
[CFRelease]: http://developer.apple.com/library/mac/documentation/CoreFoundation/Reference/CFTypeRef/Reference/reference.html#//apple_ref/c/func/CFRelease
68147
[CFDataCreateWithBytesNoCopy]: http://developer.apple.com/library/mac/documentation/CoreFoundation/Reference/CFDataRef/Reference/reference.html#//apple_ref/c/func/CFDataCreateWithBytesNoCopy
148+
[CFArray]: http://developer.apple.com/library/mac/#documentation/CoreFoundation/Reference/CFArrayRef/Reference/reference.html
149+
[CFDictionary]: http://developer.apple.com/library/mac/#documentation/CoreFoundation/Reference/CFDictionaryRef/Reference/reference.html
150+
[CFDictionaryCreate]: http://developer.apple.com/library/mac/documentation/CoreFoundation/Reference/CFDictionaryRef/Reference/reference.html#//apple_ref/c/func/CFDictionaryCreate
151+
[-mutableCopy]: http://developer.apple.com/library/mac/#documentation/Cocoa/Reference/Foundation/Classes/NSObject_Class/Reference/Reference.html%23//apple_ref/occ/instm/NSObject/mutableCopy
152+
[-copy]: http://developer.apple.com/library/mac/#documentation/Cocoa/Reference/Foundation/Classes/NSObject_Class/Reference/Reference.html%23//apple_ref/occ/instm/NSObject/copy
153+
[-retain]: http://developer.apple.com/library/mac/documentation/Cocoa/Reference/Foundation/Protocols/NSObject_Protocol/Reference/NSObject.html#//apple_ref/occ/intfm/NSObject/retain
154+
[-release]: http://developer.apple.com/library/mac/documentation/Cocoa/Reference/Foundation/Protocols/NSObject_Protocol/Reference/NSObject.html#//apple_ref/occ/intfm/NSObject/release
155+
[-isEqual:]: http://developer.apple.com/library/mac/documentation/Cocoa/Reference/Foundation/Protocols/NSObject_Protocol/Reference/NSObject.html#//apple_ref/occ/intfm/NSObject/isEqual:
156+
[-hash]: http://developer.apple.com/library/mac/documentation/Cocoa/Reference/Foundation/Protocols/NSObject_Protocol/Reference/NSObject.html#//apple_ref/occ/intfm/NSObject/hash
157+
[NSArray]: http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray_Class/index.html
158+
[NSDictionary]: http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSDictionary_Class/index.html
69159
[NSData]: http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSData_Class/index.html
160+
[printf]: http://developer.apple.com/library/mac/#documentation/Darwin/Reference/ManPages/man3/printf.3.html

‎JSONKit.h

Lines changed: 4 additions & 101 deletions
Original file line numberDiff line numberDiff line change
@@ -79,84 +79,9 @@ typedef unsigned int NSUInteger;
7979
#define _JSONKIT_H_
8080

8181
#define JSONKIT_VERSION_MAJOR 1
82-
#define JSONKIT_VERSION_MINOR 3
82+
#define JSONKIT_VERSION_MINOR 4
8383

84-
typedef NSUInteger JKHash;
8584
typedef NSUInteger JKFlags;
86-
typedef NSUInteger JKTokenType;
87-
typedef JKFlags JKManagedBufferFlags;
88-
typedef JKFlags JKObjectStackFlags;
89-
90-
typedef struct {
91-
unsigned char *ptr;
92-
size_t length;
93-
} JKPtrRange;
94-
95-
typedef struct {
96-
const unsigned char *ptr;
97-
size_t length;
98-
} JKConstPtrRange;
99-
100-
typedef struct {
101-
size_t location, length;
102-
} JKRange;
103-
104-
typedef struct {
105-
JKPtrRange bytes;
106-
JKManagedBufferFlags flags;
107-
size_t roundSizeUpToMultipleOf;
108-
} JKManagedBuffer;
109-
110-
typedef struct {
111-
void **objects, **keys;
112-
JKHash *hashes;
113-
size_t *sizes;
114-
size_t count, index, roundSizeUpToMultipleOf;
115-
JKObjectStackFlags flags;
116-
} JKObjectStack;
117-
118-
typedef struct {
119-
JKPtrRange bytes;
120-
} JKBuffer;
121-
122-
typedef struct {
123-
JKConstPtrRange bytes;
124-
} JKConstBuffer;
125-
126-
typedef NSUInteger JKValueType;
127-
128-
typedef struct {
129-
JKConstPtrRange ptrRange;
130-
JKHash hash;
131-
JKValueType type;
132-
union {
133-
long long longLongValue;
134-
unsigned long long unsignedLongLongValue;
135-
double doubleValue;
136-
} number;
137-
} JKTokenValue;
138-
139-
typedef struct {
140-
JKConstPtrRange tokenPtrRange;
141-
JKTokenType type;
142-
JKTokenValue value;
143-
JKManagedBuffer tokenBuffer;
144-
} JKParseToken;
145-
146-
147-
typedef struct {
148-
void *object;
149-
JKHash hash;
150-
size_t size;
151-
unsigned char *bytes;
152-
JKValueType type;
153-
unsigned char age;
154-
} JKTokenCacheItem;
155-
156-
typedef struct {
157-
JKTokenCacheItem *items;
158-
size_t count, clockIdx;
159-
} JKTokenCache;
16085

16186
/*
16287
JKParseOptionComments : Allow C style // and /_* ... *_/ (without a _, obviously) comments in JSON.
@@ -177,29 +102,6 @@ enum {
177102
};
178103
typedef JKFlags JKParseOptionFlags;
179104

180-
typedef id (*NSNumberAllocImp)(id object, SEL selector);
181-
typedef id (*NSNumberInitWithUnsignedLongLongImp)(id object, SEL selector, unsigned long long value);
182-
183-
typedef struct {
184-
Class NSNumberClass;
185-
NSNumberAllocImp NSNumberAlloc;
186-
NSNumberInitWithUnsignedLongLongImp NSNumberInitWithUnsignedLongLong;
187-
} JKObjCImpCache;
188-
189-
typedef struct {
190-
JKParseOptionFlags parseOptionFlags;
191-
JKConstBuffer stringBuffer;
192-
size_t atIndex, lineNumber, lineStartIndex;
193-
size_t prev_atIndex, prev_lineNumber, prev_lineStartIndex;
194-
int errorIsPrev;
195-
JKParseToken token;
196-
JKObjectStack objectStack;
197-
JKTokenCache cache;
198-
JKObjCImpCache objCImpCache;
199-
NSError *error;
200-
} JKParseState;
201-
202-
203105
enum {
204106
JKSerializeOptionNone = 0,
205107
JKSerializeOptionPretty = (1 << 0), // Not implemented yet...
@@ -208,13 +110,14 @@ enum {
208110
};
209111
typedef JKFlags JKSerializeOptionFlags;
210112

211-
212113
#ifdef __OBJC__
213114

115+
typedef struct JKParseState JKParseState; // Opaque internal, private type.
116+
214117
// As a general rule of thumb, if you use a method that doesn't accept a JKParseOptionFlags argument, it defaults to JKParseOptionStrict
215118

216119
@interface JSONDecoder : NSObject {
217-
JKParseState parseState;
120+
JKParseState *parseState;
218121
}
219122
+ (id)decoder;
220123
+ (id)decoderWithParseOptions:(JKParseOptionFlags)parseOptionFlags;

0 commit comments

Comments
 (0)