Preface
For many historical reasons, the TXT engine in the QQ Reader iOS app could only load, lay out, and render a single file at a time. When switching online chapters, the app had to close the engine for the current chapter, clean up all business data, reload the engine for the new chapter, and request the new chapter’s business data again.
This caused two serious problems:
- When turning pages back and forth around the boundary between two chapters, the engine had to repeatedly open and close chapters, which was expensive.
- In 3D page-turning mode, chapter switching required forced page turns. In other words, the user could not fully control the 3D effect through gestures, and there was no chance to cancel the turn and roll back.
So we needed to refactor the TXT engine’s multi-chapter switching process and support seamless chapter switching with minimal cost.
The original motivation for this refactor was actually to see whether we could remove the top crash in RDM.
All pain comes from not having enough knowledge of, or enough respect for, history.
Current State
Overall Architecture
TextBaseViewControllerholdsQRReadingDataSource.QRReadingDataSourceis responsible for loading chapter data and various business data.QRReadingDataSourceholdsReaderRender, andReaderRenderalso holds it back.ReaderRenderis responsible for page drawing, including views corresponding to various business data.- Everything related to the engine is operated through
Hub. At the bottom,TextEngineis responsible for loading, laying out, and rendering concrete chapter files.- The view controllers for 3D page turning, smooth page turning, and cover page turning all weakly hold
TextBaseViewControllerdirectly and call methods on it. As a result,TextBaseViewControllerhas to expose many interfaces for them.
All those ownership and reverse-ownership relationships made the coupling painfully deep.
File Opening Flow
- The call hierarchy for opening a file is too deep. Some logic lives in
OpenBookManager, some inTextBaseViewController, and the flow is scattered. Because of that, notifications are used for synchronization. This kind of dispersed logic is very tiring to read.- Chapter loading contains preload logic, but it only covers chapter data. Paid preview information is not cached, so every time the reader turns to a new chapter, a symbolic loading state appears.
- Other business logic is scattered across
TextBaseViewControllerandQRReadingDataSource. There is no unified synchronization mechanism. Every kind of business data is requested separately, and each response may refresh the reading page to some degree, increasing refresh pressure.
Hub Calls
The Hub mechanism essentially turns the underlying
TextEngine into a singleton, which means it can be called
from almost anywhere without restraint. An initial count looked like
this:
| File | Count |
|---|---|
| QRReadingDataSource | 3 |
| ReaderRender | 33 |
| TextBaseViewController | 47 |
The Refactoring Path
Establishing the Cache Model
To avoid unnecessary waste when switching to the next chapter, we cannot immediately close the previous chapter’s information. Instead, we need to cache it. If the user turns back, we can reuse the cache without reopening the chapter. This also improves the page-turning experience, so a cache model naturally emerged.
Three-Engine Architecture
The first idea was a three-engine architecture: create an engine
wrapper named QRTextEngine, and let it hold three
TextEngine instances internally to implement preloading and
chapter switching.
When the current chapter is close to its final page, for example when
progress reaches 80%, preload logic is triggered.
nextTextEngine asynchronously loads the next chapter on a
background thread. When the reader really switches to the next chapter,
we only need to point curTextEngine to
nextTextEngine to complete the engine switch.
1 | @interface QRTextEngine()<TextEngineDelegate>{ |
1 | - (void)switchToNextEngine |
In practice, however, this cache model had several problems:
- Not every chapter has chapter data. Some chapters may not be paid for, so there may be no file at all. In that case,
TextEngineis empty and switching fails.- Paid preview information is not cached. It has to be requested every time, wasting a lot of traffic and creating an uncomfortable loading wait.
- States such as
[engine nil engine]and[nil engine nil]can appear. If switching logic is not controlled carefully, things become inconsistent. To work around this, we had to perform a fake file open.- The cache was not thorough enough. Business cache logic for chapters still had to be handled elsewhere. A unified behavior was split apart.
Three-Model Architecture
After discovering the limitations of the three-engine architecture, I introduced a three-model architecture:
The model no longer refers only to an engine. It becomes a chapter
model, QRTextReaderChapterModel. It includes not only
TextEngine, but also authorization information such as paid
previews, and even various chapter-level business data such as chapter
comments and paragraph comments.
The problems in the previous three-engine design are then naturally solved:
- Every chapter now has data. Downloaded chapters have renderable chapter data, while unavailable chapters have paid-preview data. Page switching becomes possible in any direction.
- Paid preview information is cached and can be requested only once within a given time window.
- Business data cache logic is handled uniformly. The reading page is refreshed only after all business data returns, reducing refresh pressure.
Refactored Class Diagram
Once the cache model was established, the overall architecture of the refactor was basically determined.
- For TXT books, opening a book no longer directly calls
OpenBookManager.OpenBookManageris now only responsible for creating the view controller, passingBookInfoto it, and pushing it.- The original
QRReadingDataSourceandReaderRenderare removed. The new manager class,QRTextReaderManager, takes over the core logic.- Page-turning view controllers no longer weakly hold
TextBaseViewControllerdirectly. Instead, they receiveQRTextReaderManagerand call its interfaces.- The three-model architecture is managed directly by
QRTextReaderManager. Therefore,QRTextReaderManageris responsible for creating, preloading, switching, and destroying the three models.QRTextReaderChapterModelis responsible for chapter file requests and loading,TextEngineinitialization, paid-preview requests and cache management, business data requests and loading, and callingQRTextEngineto lay out and render pages.
QRTextReaderManager
QRTextReaderManager coordinates the TXT reading
logic.
In the earliest design, I used the three-engine architecture, where
QRTextEngine directly held three TxtEngine
engines and handled their creation, preloading, switching, and
destruction. But this did not handle chapter network states well, such
as paid chapters, login-required chapters, or removed chapters. To solve
various strange issues and ensure continuity during internal engine
switching, I even introduced the idea of opening a fake engine.
Eventually I abandoned it, because the real problem was in the overall
structure. Patching it would only lead us deeper into trouble.
So the original three-engine architecture became a three-model
architecture. The old version was managed by QRTextEngine,
while the new three-model architecture is managed directly by
QRTextReaderManager. Therefore,
QRTextReaderManager needs to handle creation, preloading,
switching, and destruction of these three models.
There were also many fields in TextBaseViewController
used for logic checks. Since QRTextReaderManager now
carries that logic, those fields need to move downward into the
manager.
QRTextReaderChapterModel
QRTextReaderChapterModel is the core support for
coordinating TXT reading logic.
The final design wraps QRTextReaderChapterModel around
QRTextEngine. This class contains both chapter
network-state information, authorizeInfo, and local file
information plus the engine used to load the file. These
two states are mutually exclusive. At any given moment, only one can
exist, and there is a transition from network state to local state.
- In network state,
QRTextReaderChapterModeluses the information inauthorizeInfoto generate a view.- In local state,
QRTextReaderChapterModeluses theengineto lay out and render page images, adds headers and footers, and generates a view. It also callsQRTextBusinessManagerto asynchronously load and manage various business data. After the data returns, it refreshes the reading page uniformly.
Note: all chapter loading, including preloading, should go through
QRTextReaderChapterModel. Only then can each chapter’s
state be clearly tracked, preventing duplicate loading and resource
waste.
How should the page be refreshed after all business data returns? Here I used a simple approach:
Each type of business data has a dedicated property marking its
state. When it is marked YES, it attempts to call
handleBusinessDataIfNecessary. That method checks whether
all business data is ready and then triggers one unified callback
refresh. The prerequisite is that all business-data callbacks run on the
main thread.
1 | @weakify(self) |
QRTextBusinessManager
QRTextBusinessManager carries all business logic for a
TXT chapter, including chapter comments, paragraph comments, author
Q&A, ads, voting, red packets, and so on. In practice, it is also a
simple wrapper. Each business type still has its own class.
After a chapter’s information, either network-state information or a
local file, becomes ready, QRTextBusinessManager is used to
load business data. QRTextReaderChapterModel also records
the state of each business data request: not requested, requesting, or
finished.
- QA: author Q&A, chapter business.
- Advertisements: ad data, chapter business.
- InteractionBar: bottom area of the chapter tail page, including rewards, recommendation tickets, monthly tickets, red packets; book-level business.
- Comments: chapter comments, chapter business.
- ParagraphTailMark: paragraph comments, chapter business.
After the git branch merge, new business items were added to the tail
page, such as Guangdiantong ads and cards. Card data uses the
chapterall protocol and returns together with other
business data. Guangdiantong ads use an independent protocol and have
more complex business logic, so their logic was placed separately in
QRChapterBusinessManager+GDTAd.h. Like the other business
data, it is processed uniformly when the callback returns.
1 | - (void)setAlreadyGetGDTTailAd:(BOOL)alreadyGetGDTTailAd |
QRTextEngine Wrapper
This is a simple wrapper around TextEngine. It mainly
replaces the role of the original EngineModule, but it is
no longer a singleton.
Chapter Loading Logic
All chapter loading and preloading should start from
QRTextReaderChapterModel. It is the entry point. Once
loading starts, the state of QRTextReaderChapterModel must
be updated continuously.
In the latest code, there is only one trigger point for preloading:
when the chapter ID changes or when onlineTag is
modified.
1 | - (void)setOnlineTag:(OnlineTag *)onlineTag |
The preloaded content includes two parts:
- Chapter information, which may be a file or paid-preview information.
- All business data related to the chapter. These business types are complex, and some of them already affect page layout.
QRTextReaderChapterModel records the current preload
progress at all times.
Refactoring the File Opening Flow
- Remove the notifications accumulated along the way and use callbacks instead, gathering logic that was previously scattered by notifications.
- Remove the preload logic in
QROnlineReadingModule, which was responsible for pre-downloading free chapters. Now the preload entry point should always start fromQRTextReaderChapterModel, andQRTextReaderChapterModelshould record chapter state.
In theory, QROnlineReadingModule should not know the
OnlineTag of the current reading chapter.
The expected logic is: given an OnlineTag, it is only
responsible for cache lookup, starting downloads, and network-result
callbacks. The final result should be passed back to
QRTextReaderChapterModel.
- If the current chapter is chapter 0, it represents the cover. Return directly and finish.
- If the current chapter has already been downloaded, return the chapter file path to
QRTextReaderChapterModeland finish.- Otherwise, make a network request for the current chapter information and wait for the result:
- If the result is a downloaded chapter file, follow step 2.
- If authorization is required, such as payment, login, or removed content, return the result to
QRTextReaderChapterModel.
Removing Hub
- For imported books, add
QRTextEngineParserto handle parsing logic.- For chapter layout and rendering, use the
QRTextEnginemember namedengineinsideQRTextReaderChapterModel. The original Hub was essentially a singleton that could be used without limits from any file in the project. Nowengineexists as a member ofcurChapterModel, soQRTextReaderManagerneeds to wrap engine operations and expose the external engine interfaces.engineno longer talks directly to the outside world.- For statistics, Hub’s original statistics logic lived in
StatisticModule. To completely removeHub, addQRStatisticManagerand move most of the originalStatisticModulelogic into it. The remaining small pieces callQRBookManagerorAppPersistdirectly.
Note: during replacement, pay attention to Hub’s input parameter
inputMessage and output parameter
outputMessage. The distinction is sometimes unclear, and
inputMessage can also be used as an output parameter. Be
careful here.
Page Turning
Checks Before Page Turning
No matter which page-turning mode is used, checks are required before turning:
- Whether the current page supports turning backward. If the current page is already the cover or first page, it cannot continue backward.
- Whether the current page supports turning forward. If the current page is already the last page of the last chapter, it cannot continue forward.
- If the current page is loading, page turning is disabled.
- Page-turn frequency control.
For details, see:
1 | // TextBaseViewController+PageViewController.h |
Page-Turning Logic
Page turning may produce the following behaviors:
- If turning within the same chapter,
TextEngineswitches to the corresponding page index and renders in real time. - If turning across chapters, there are three cases:
- If chapter data is already ready,
TextEngineswitches to the corresponding page index, or uses preloaded paid-preview data, and renders in real time. - If the chapter has not been loaded, first show a loading page, then load chapter data and refresh through callback after completion.
- If the chapter is currently loading, first show a loading page and set a flag that a refresh is needed. After loading completes, refresh back.
- If chapter data is already ready,
Here is an example of switching to the next chapter:
1 | - (void)gotoNextChapter |
3D Page Turning
For gesture-based page turning, the handling is relatively simple.
There is no need to care about the user’s swipe area.
UIPageViewController automatically determines whether the
user is turning forward or backward, and eventually calls several
important delegate methods:
1 | // UIPageViewControllerDelegate |
Gesture-driven 3D page turning supports rollback: the 3D animation can reach halfway and then return. But page-turning logic has already happened when the 3D animation starts, so if the animation rolls back, the page index must be corrected. The reason is that the data source has already changed at animation start, so when rolling back, the data source needs to be restored.
Under the new architecture, there are two cases:
- If rollback happens within the same chapter, adjust the page index inside the chapter.
- If rollback happens across chapters, it involves switching between chapter models.
1 | // When preVC's chapterId differs from ReaderManager's chapterId, |
There is another problem with 3D gesture page turning: network-result callbacks may refresh the page during the 3D animation, causing strange behavior. The solution is to avoid refreshing directly at that moment. Instead, store the refresh logic as a block and execute it after the page-turn animation finishes.
1 | void (^refreshBlock)() = ^{...}; |
1 | - (void)pageViewController:(UIPageViewController *)pageViewController didFinishAnimating:(BOOL)finished previousViewControllers:(NSArray *)previousViewControllers transitionCompleted:(BOOL)completed |
For tap-based page turning, the logic is more complex. First, we need
to understand how UIPageViewController handles tap
areas:
Only taps in the sky-blue areas on the left and right trigger the
same logic as gestures in UIPageViewController. Other areas
do not respond, so custom handling is required there. Depending on the
required region, we call the following method to turn forward or
backward:
1 | - (void)setViewControllers:(nullable NSArray<UIViewController *> *)viewControllers direction:(UIPageViewControllerNavigationDirection)direction animated:(BOOL)animated completion:(void (^ __nullable)(BOOL finished))completion; |
This introduces two concepts: system tap area and custom tap area.
Area detection:
For concrete tap-area detection logic, see:
1 | - (QRTurnDirection)system3DAreaDirectionWithRect:(CGRect)rect point:(CGPoint)point; |
Page Turning Without Animation
No-animation page turning is based on 3D page turning with the animation removed:
1 | [self loadPageViewControllerWithStyle:UIPageViewControllerTransitionStylePageCurl |
The tap areas are shown below:
Smooth Page Turning
Smooth page turning mainly uses two views, one above and one below, and preloads the previous and next pages in real time. This refactor mainly changed the preload logic.
Originally, nextPageInfo could only get next-page
information within the current chapter and could not cross chapter
boundaries. Now that the engine layer supports opening multiple
chapters, we can consider fetching the next chapter’s information across
chapter boundaries. If the next chapter has already been downloaded, the
already-opened engine can lay it out, render it, and return the result.
Otherwise, it preloads and waits for callback refresh.
1 | - (QRReadingPageInfo *)nextPageInfo |
Unlike 3D page turning, when smooth page turning crosses chapters, the next page fetched during the animation is only preloaded data. The real switch to the next chapter does not happen during the animation. In 3D page turning, the chapter has already switched during the animation. This is why 3D page turning needs to adjust the page index when rolling back, while smooth page turning does not.
The real chapter switch for smooth page turning is triggered by the callback after the animation finishes:
1 | - (void)dragAnimationFinished:(BOOL)popSuccess toNext:(BOOL)toNext |
Cover Page Turning
Cover page turning is similar to smooth page turning overall. During the animation, it only takes preloaded data and does not perform the real page turn. The real turn happens after the animation completes:
1 | - (void)didCoverFinish{ |
The online cover-turning effect always felt visually a bit laggy. To improve user experience, I used a small-step, high-frequency strategy: reduce the step size and increase refresh frequency.
The left side is the online effect, and the right side is the optimized effect.


Insert Page Logic
After the git version was merged, insert-page logic was added. Some ad pages are often inserted between original reading pages. But this insert-page logic was coupled with the original page-turning logic, so the first thing I did was separate them: split page-turning logic from insert-page logic.
1 | - (void)didTrunPageToPrev |
1 | - (void)invokePrevPageInsertLogic:(NSInteger)pageIndex block:(void(^)())block |
This allows insert-page logic to be plugged in like a plugin. The original page-turning logic is passed to the insert manager as a block, so future changes inside insert-page logic will not affect page-turning logic, and vice versa.
For more details, see QRTextReaderManager+Insert.m.
At the same time, the continuation logic involved in insert pages will be redesigned and implemented together with Siyu.
Page Cache
A Global View of Cache
In the chapter-switching version, the words preload and cache appear repeatedly. But these caches are not immutable. Sometimes they need to be updated. For example, when options are changed and the current page needs to be updated, the page currently displayed and other preloaded page caches must all be updated.
So we need a global view of cache.
Here are some examples:
- Suppose the reader reaches a paid-preview page, and both the previous and next chapters are also paid-preview pages. If the user taps purchase, the current chapter model needs to be removed, rebuilt, reloaded, and rendered again. But if auto-purchase happens to be enabled when the user taps purchase, the other two preloaded paid-preview pages should also become invalid and be removed from cache. Similarly, if auto-purchase is deliberately disabled during purchase, the auto-purchase flag in other preloaded paid-preview pages should also be turned off.
- Suppose three consecutive chapters have all been rendered. If the font size changes or the device rotates, then besides the current chapter, the other two cached chapter models should first clear their rendered pages and then update their engine settings. Otherwise, problems will appear.
Mode Changes
- Changes in the following information all need to call
relayoutReaderEngineto refresh the reading page:
- Reading mode changes: 3D, smooth, no effect, cover page turning, TTS.
- Rotation.
- Font changes and font-size changes.
1 | - (void)relayoutReaderEngine // The reading engine needs relayout when switching reading mode. |
The key point here is:
Business data handling through
handleTailPagePlaceholder must be called after
relayout; otherwise paragraphs may be lost. This is because
handleTailPagePlaceholder inserts custom business
paragraphs into an already-built paragraph linked list, while
relayout discards all paragraphs and rebuilds them from
chapter data.
Layout Setting Changes
QRSetting exists as a setting property of
QRTextReadManager. If the user changes layout settings and
causes it to change, corresponding handling is required.
- Clear previously laid-out page caches:
1 | - (void)flushPageCache |
- Update all loaded
TextEngineinstances:
1 | - (void)setSetting:(QRSetting *)setting |
Screen Rotation
Rotation changes the drawing area, so rendered pages need to be cleared and redrawn.
P.S. There had long been an online issue where paragraph comments disappeared during rotation. The root cause was that rotation triggered relayout.
The workaround was to perform a round trip:
1 | - (void)resumeEngineState |
Later, I found that the main branch had already fixed this issue, so this change could be reverted.
Page Changes Caused by Business Data
- Clear rendered page caches.
- Update business placeholders.
1 | // Set the placeholder area for the chapter tail page. |
Clearing Cache During Page Turning
- The current chapter keeps at most three page caches. Once there are more than three, caches are cleared.
- Preloaded previous and next chapters each keep at most one page. If
the chapter has no data and the engine is
nil, this may be zero.
Summary
The TXT chapter-switching refactor continued intermittently for more than half a year and went through two versions.
The first version was experimental and relatively lightweight. It did not touch the core architecture, so progress was fast, but it also had many issues. Because the refactor was not thorough enough, we hit performance bottlenecks that could not be improved no matter how much we optimized. So I made the painful decision to overturn it and start a more complete 2.0 refactor. During that process, I discussed it many times with Feng and tried many approaches. I also learned quite a few lessons from it.
Version 2.0 went through more than 40 days of compile errors, black pages when it first started running, and stumbling crashes. At the time of writing, progress was about 70-80%. The remaining work has been shelved since mainline 7.0 development started.
Before migrating to git, the code was merged again and then migrated to git.
Notes
SVN address for version 1.0, with 52 commits:
1 | http://bj-scm.tencent.com/mqq/mqq_book_rep/QQReader_iPhone_proj/branches/QQReader_TxtMultiChaptersLoad_1.0 |
SVN address for version 2.0, with 22 commits:
1 | http://bj-scm.tencent.com/mqq/mqq_book_rep/QQReader_iPhone_proj/branches/QQReader_TxtMultiChaptersLoad_3.0 |
Git address, with 34 commits:
1 | http://git.code.oa.com/qq_reader_mobile_tech_ios/QQReader_iPhone_Proj |
Pitfall Notes
1. Broken Layout for “Brilliant Ideas”
After investigation, I found a problem in this piece of code:
1 | - (TextPrgf_ptr_t)_paragraphWithIdentifier:(NSInteger)paraIdentifier |
Here, paraIdentifier represents the paragraph index.
paraList stores the offset of each paragraph in the current
chapter in order. But if the reader opens the book from the middle of a
chapter, a complete paragraph linked list cannot be built. This means
_prgfGroup.head starts from a paragraph in the middle.
According to the logic above, if paraOffset is smaller
than _prgfGroup.head, then the final paragraph
found is wrong. That wrong paragraph did not reserve layout space for
“brilliant ideas”, so position overlap and broken layout appeared.
Once the cause was found, the fix was simple: after finding the
paragraph offset corresponding to paraIdentifier, compare
it with _prgfGroup.head’s offset first. If it is smaller,
return NULL directly.
1 | // Find the offset of the paragraph corresponding to paraIdentifier. |
Why did this problem not happen on the main branch? After
investigation, the reason was that the main-branch code pre-rendered the
previous page while rendering the current page. This built the paragraph
linked list before the current anchor. Since online-book chapter files
are usually small, _prgfGroup.head would then be built as
the first paragraph of the chapter, so the issue above would not
appear.
1 | if (![self isTopPage]) |
2. Preload Hang
During chapter switching, intermittent hangs often occurred. Through logging and debugging, I found that the chapter-file download completion callback sometimes ran before the progress callback:
1 | 2019-04-18 16:11:18.942489+0800 QQReaderUI[97099:5778241] end callback: 异常:0, 8192, <NSHTTPURLResponse: 0x600003c3ccc0> { Status Code: 200, Headers { |
At this point, the data had not actually been fully received, but a callback had already triggered a refresh, causing the hang. A normal chapter download should look like this:
1 | 2019-04-18 16:11:51.987733+0800 QQReaderUI[97099:5777779] progress callback: 进度 9216, 9216 , <NSMutableURLRequest: 0x600003f3ab10> |
The cause was related to callbacks in QQHttpClient.
- A session instance can set
completionQueue, and callback blocks will execute on that queue.- If
completionQueueis not set:- If
[QQHttpClient enqueueRequestSession:session]is called on the main thread, callbacks run on the main thread.- If
[QQHttpClient enqueueRequestSession:session]is called on a background thread, callbacks run on the default concurrent queue.
1 | if (!session.completionQueue){ |
Because this was preload logic, the network request was initiated on
a background thread and completionQueue was not set
beforehand. So callbacks defaulted to a background thread. However, the
progress callback in QQHttpClientSession actively switched
to the main thread, causing the progress callback to happen after the
completion callback.
1 | if (self.downloadProgress) |
In theory, this should not automatically switch to the main thread. Whether on the main thread or a background thread, the progress callback and completion callback should stay on the same thread. But because the code was old and not suitable for broad changes, the solution here was to uniformly set chapter-download network callbacks to the main thread.
1 | // Set callback queue to main queue. |
3. Heap Corruption
Recently, the reading page had been crashing frequently. The timing and location were very random, and each time it printed this message:
1 | QQReaderUI(1728,0x10ab9eb80) malloc: Heap corruption detected, free list is damaged at 0x282ecaac0 |
Setting up exception capture did not help and provided no useful clues.
Eventually, through the coincidence of a dead loop, I found the problem:
The tail-page logic inside TxtEngine contains
various priority rules. “Author’s notes” are technically business data,
but they happen to live inside chapter data. Every time chapter layout
finishes, the parsed author’s notes need to be passed out to the
business layer, where priority sorting is performed. Later, the engine
asks for the sorted data. In some cases, however, the engine needs to
relayout and releases the previously passed-out author’s-note data.
Since an author’s note itself is a C struct pointer, the outside
business layer has no way to know that the engine has released it. The
real root cause is still a bug in the code. The next time the engine
asks for data, the business layer passes an already released invalid
pointer back to the engine. The engine then performs illegal memory
operations, causing a crash.