Refactoring TXT Engine Chapter Switching

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

Refactoring TXT Engine Chapter Switching: Overall Architecture (figure 1)
  • TextBaseViewController holds QRReadingDataSource. QRReadingDataSource is responsible for loading chapter data and various business data.
  • QRReadingDataSource holds ReaderRender, and ReaderRender also holds it back. ReaderRender is responsible for page drawing, including views corresponding to various business data.
  • Everything related to the engine is operated through Hub. At the bottom, TextEngine is 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 TextBaseViewController directly and call methods on it. As a result, TextBaseViewController has to expose many interfaces for them.

All those ownership and reverse-ownership relationships made the coupling painfully deep.

File Opening Flow

Refactoring TXT Engine Chapter Switching: File Opening Flow (figure 2)
  • The call hierarchy for opening a file is too deep. Some logic lives in OpenBookManager, some in TextBaseViewController, 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 TextBaseViewController and QRReadingDataSource. 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.

Refactoring TXT Engine Chapter Switching: Three-Engine Architecture (figure 3)

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
2
3
4
5
6
@interface QRTextEngine()<TextEngineDelegate>{
@property(nonatomic,strong) TextEngine *preEngine;
@property(nonatomic,strong) TextEngine *curEngine;
@property(nonatomic,strong) TextEngine *nextEngine;
...
@end
1
2
3
4
5
6
7
8
- (void)switchToNextEngine
{
[self syncPerformBlockOnEngineQueue:^{
self.preEngine = self.curEngine;
self.curEngine = self.nextEngine;
self.nextEngine = nil;
}];
}

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, TextEngine is 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:

Refactoring TXT Engine Chapter Switching: Three-Model Architecture (figure 4)

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.

Refactoring TXT Engine Chapter Switching: Refactored Class Diagram (figure 5)

High-resolution diagram

  • For TXT books, opening a book no longer directly calls OpenBookManager. OpenBookManager is now only responsible for creating the view controller, passing BookInfo to it, and pushing it.
  • The original QRReadingDataSource and ReaderRender are removed. The new manager class, QRTextReaderManager, takes over the core logic.
  • Page-turning view controllers no longer weakly hold TextBaseViewController directly. Instead, they receive QRTextReaderManager and call its interfaces.
  • The three-model architecture is managed directly by QRTextReaderManager. Therefore, QRTextReaderManager is responsible for creating, preloading, switching, and destroying the three models.
  • QRTextReaderChapterModel is responsible for chapter file requests and loading, TextEngine initialization, paid-preview requests and cache management, business data requests and loading, and calling QRTextEngine to 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, QRTextReaderChapterModel uses the information in authorizeInfo to generate a view.
  • In local state, QRTextReaderChapterModel uses the engine to lay out and render page images, adds headers and footers, and generates a view. It also calls QRTextBusinessManager to 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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
@weakify(self)
[self.businessMgr loadAllBusinessDataWithReadyCallback:^(NSError *error, NSDictionary* dic) {

@strongify(self)

// Process all data for each chapter together.
[self handleTailPagePlaceholder];
[self handleChapterCommentResponse:dic];
[self handleExcellentParaComment];

// Engine
if(self.loadPoint == QRChapterLoadPointType_End){
[self turnToFinalPage];
}

// Clear cache after business data returns.
[self flushPageCache];

// After all business data returns, notify the delegate and check whether the reading page needs refresh.
NSDictionary* result = @{QROnlineReadingResultKeys.result:@(QRReadOnlineBookResult_Opened)};
[self.delegate chapterModel:self didFinishLoadWithResult:result];

}];

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
2
3
4
5
- (void)setAlreadyGetGDTTailAd:(BOOL)alreadyGetGDTTailAd
{
_alreadyGetGDTTailAd = alreadyGetGDTTailAd;
[self handleBusinessDataIfNecessary];
}

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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
- (void)setOnlineTag:(OnlineTag *)onlineTag
{
if(!onlineTag) { return; }
_onlineTag = onlineTag;

_chapterModel = [self chapterModelWithOnlineTag:onlineTag];
if(_chapterModel.bookInfo != nil){
self.bookInfo = _chapterModel.bookInfo;
}

// Report
[self reportOnlineBookWithTag:_onlineTag];

// Save reading history. lucas
if (self.onlineTag.onlineBookInfo) {
[[QRScanHistoryService sharedScanHistoryService] recordScanHistoryItem:self.onlineTag.onlineBookInfo];
}

NSArray *allKeys = [self.chapterModels allKeys];
NSInteger chapterId = [@(self.chapterModel.chapterId) integerValue];
for (NSNumber *key in allKeys){
NSInteger keyValue = [key integerValue];
if (ABS(keyValue - chapterId) > 1){
[self.chapterModels removeObjectForKey:key];
}
}

// Async preload logic
[self asyncPerformBlockOnChapterProloadQueue:^{

// After chapter switching, keep at most one page cache for previous and next chapters.
QRTextReaderChapterModel* preModel = [self.chapterModels qr_safeObjectForKey:@(chapterId-1)];
[preModel removeAllPageCacheExceptTheLastOne];
QRTextReaderChapterModel* nextModel = [self.chapterModels qr_safeObjectForKey:@(chapterId+1)];
[nextModel removeAllPageCacheExceptTheFirstOne];


if(self.onlineTag.onlineBookInfo.chapterid < self.onlineTag.onlineBookInfo.totalChapter){
OnlineTag* nextOnlineTag = [self onlineTagWithTag:self.onlineTag direction:QRTurnDirection_Next];
[nextOnlineTag resetProgress];
nextOnlineTag.rightParameter = CHAPTER_CUR;
QRTextReaderChapterModel* nextModel = [self chapterModelWithOnlineTag:nextOnlineTag];
if(nil == nextModel){
[self proloadChapterModelWithOnlineTag:nextOnlineTag];
}
}

if(self.onlineTag.toReadingCharpterId > 0){
OnlineTag* prevOnlineTag = [self onlineTagWithTag:self.onlineTag direction:QRTurnDirection_Prev];
[prevOnlineTag resetProgress];
prevOnlineTag.rightParameter = CHAPTER_CUR;
QRTextReaderChapterModel* preModel = [self chapterModelWithOnlineTag:prevOnlineTag];
if(nil == preModel){
[self proloadChapterModelWithOnlineTag:prevOnlineTag];
}
}
}];
}

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

Refactoring TXT Engine Chapter Switching: Refactoring the File Opening Flow (figure 6)

High-resolution diagram

  1. Remove the notifications accumulated along the way and use callbacks instead, gathering logic that was previously scattered by notifications.
  2. Remove the preload logic in QROnlineReadingModule, which was responsible for pre-downloading free chapters. Now the preload entry point should always start from QRTextReaderChapterModel, and QRTextReaderChapterModel should 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 QRTextReaderChapterModel and 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 QRTextEngineParser to handle parsing logic.
  • For chapter layout and rendering, use the QRTextEngine member named engine inside QRTextReaderChapterModel. The original Hub was essentially a singleton that could be used without limits from any file in the project. Now engine exists as a member of curChapterModel, so QRTextReaderManager needs to wrap engine operations and expose the external engine interfaces. engine no longer talks directly to the outside world.
  • For statistics, Hub’s original statistics logic lived in StatisticModule. To completely remove Hub, add QRStatisticManager and move most of the original StatisticModule logic into it. The remaining small pieces call QRBookManager or AppPersist directly.

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
2
// TextBaseViewController+PageViewController.h
- (BOOL)gestureRecognizerShouldBegin:(UIGestureRecognizer *)gestureRecognizer

Page-Turning Logic

Page turning may produce the following behaviors:

  1. If turning within the same chapter, TextEngine switches to the corresponding page index and renders in real time.
  2. If turning across chapters, there are three cases:
    • If chapter data is already ready, TextEngine switches 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.

Here is an example of switching to the next chapter:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
- (void)gotoNextChapter
{
if(!self.isOnlineRead) { return;}

@synchronized(self)
{
// Note: switching onlineTag here must be locked.
OnlineTag* nextOnlineTag = [self onlineTagWithTag:self.onlineTag direction:QRTurnDirection_Next];
[nextOnlineTag resetProgress];
nextOnlineTag.rightParameter = CHAPTER_CUR;

// Note: this triggers preload logic.
self.onlineTag = nextOnlineTag;

QRTextReaderChapterModel* chapterModel = [self chapterModelWithOnlineTag:self.onlineTag];
if(nil == chapterModel || chapterModel.type == QRChapterModelState_Failure){
if(chapterModel){
[self.chapterModels qr_safeRemoveObjectForKey:@(chapterModel.chapterId)];
}
// Create ChapterModel.
chapterModel = [self createChapterModelWithOnlineTag:self.onlineTag];
chapterModel.loadPoint = QRChapterLoadPointType_Start;

// Need to request network data.
[self proloadChapterModelWithOnlineTag:self.onlineTag];
}
else
{
chapterModel.loadPoint = QRChapterLoadPointType_Start;
if(chapterModel.type == QRChapterModelState_Loading){
// Refresh the loading page first.
[self.delegate refreshReadingPageIfNecessary];
}
else
{
// ChapterModel has already been preloaded and is ready.
if(chapterModel.type == QRChapterModelState_Rended){
// The chapter file exists and the engine is ready.
if(![self.chapterModel isPageTop]){
[self.chapterModel turnToFirstPage];
}
}
}
}
}
}

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
2
3
4
5
6
7
// UIPageViewControllerDelegate
- (void)pageViewController:(UIPageViewController *)pageViewController didFinishAnimating:(BOOL)finished previousViewControllers:(NSArray *)previousViewControllers transitionCompleted:(BOOL)completed

// UIPageViewControllerDataSource
- (UIViewController *)pageViewController:(UIPageViewController *)pageViewController viewControllerBeforeViewController:(UIViewController *)viewController;

- (UIViewController *)pageViewController:(UIPageViewController *)pageViewController viewControllerAfterViewController:(UIViewController *)viewController;

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:

  1. If rollback happens within the same chapter, adjust the page index inside the chapter.
  2. If rollback happens across chapters, it involves switching between chapter models.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// When preVC's chapterId differs from ReaderManager's chapterId,
// switch the chapter engine. If they are the same, only switch the page index.
- (void)resumePageWithCurrentId:(NSInteger)currentId
previousId:(NSInteger)previousId
previousIndex:(NSInteger)previousIndex
{
if(previousId < currentId){
// Switch engine layer back to the original chapter. Page index does not need to change.
[self gotoLastChapter];
}
else if(previousId > currentId){
// Switch engine layer back to the original chapter. Page index does not need to change.
[self gotoNextChapter];
}
else{
// Switch back to the original page index within the chapter.
[self.chapterModel resumePage];
}
}

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
2
3
4
5
6
7
8
9
10
void (^refreshBlock)() = ^{...};

if(_pageViewControllerDelegate.pageAnimationFinished){
refreshBlock();
}
else{
// If 3D page turning is in progress, refreshing directly may cause logic errors.
// It needs to be done after the animation ends.
[_pageViewControllerDelegate.callbackBlocks addObject:[refreshBlock copy]];
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
- (void)pageViewController:(UIPageViewController *)pageViewController didFinishAnimating:(BOOL)finished previousViewControllers:(NSArray *)previousViewControllers transitionCompleted:(BOOL)completed
{
self.pageAnimationFinished = YES;
...
if(completed){
while(self.callbackBlocks.count > 0){
id obj = [self.callbackBlocks qr_safeObjectAtIndex:0];
void (^block)() = (void(^)())(obj);
block();
[self.callbackBlocks qr_safeRemoveObjectAtIndex:0];
[block release];// MRC
}
}
}

For tap-based page turning, the logic is more complex. First, we need to understand how UIPageViewController handles tap areas:

Refactoring TXT Engine Chapter Switching: 3D Page Turning (figure 7)

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:

Refactoring TXT Engine Chapter Switching: 3D Page Turning (figure 8)

For concrete tap-area detection logic, see:

1
2
- (QRTurnDirection)system3DAreaDirectionWithRect:(CGRect)rect point:(CGPoint)point;
- (QRTurnDirection)customAreaDirectionWithRect:(CGRect)rect point:(CGPoint)point;

Page Turning Without Animation

No-animation page turning is based on 3D page turning with the animation removed:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
[self loadPageViewControllerWithStyle:UIPageViewControllerTransitionStylePageCurl
orientation:UIPageViewControllerNavigationOrientationHorizontal];
_pageViewAnimateNone = YES;

// Disable swiping in no-animation mode.
for (UIGestureRecognizer *gestureRecognizer in _pageViewController.gestureRecognizers)
{
if ([gestureRecognizer isKindOfClass:[UIPanGestureRecognizer class]]) {
gestureRecognizer.enabled = NO;
}
}

// Add left and right swipe gestures.
UISwipeGestureRecognizer *swipeLeft = [[[UISwipeGestureRecognizer alloc] initWithTarget:self action:@selector(swipeTurnNextPage)] autorelease];
swipeLeft.direction = UISwipeGestureRecognizerDirectionLeft;
swipeLeft.delegate = self;
[_pageViewController.view addGestureRecognizer:swipeLeft];

UISwipeGestureRecognizer *swipeRight = [[[UISwipeGestureRecognizer alloc] initWithTarget:self action:@selector(swipeTurnPreviousPage)] autorelease];
swipeRight.direction = UISwipeGestureRecognizerDirectionRight;
swipeRight.delegate = self;
[_pageViewController.view addGestureRecognizer:swipeRight];

The tap areas are shown below:

Refactoring TXT Engine Chapter Switching: Page Turning Without Animation (figure 9)

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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
- (QRReadingPageInfo *)nextPageInfo
{
if([self.chapterModel hasNextPage])
{
QRReadingPageInfo *pageInfo = [self.chapterModel nextPageInfo];

@weakify(self)
[self checkIfHitNextPageInsertLogic:self.chapterModel.pageIndex
succBlock:^(NSInteger hitPageIndex) {
@strongify(self)
pageInfo.pageDrawResultItem = [self cachePageImageWithIndex:hitPageIndex];

}
failBlock:^(id _Nullable insertItem) {
@strongify(self)
if(insertItem) {
pageInfo.pageDrawResultItem = [self.chapterModel imageForCoverPage];
pageInfo.insertItem = insertItem;
}
}];
return pageInfo;
}
else
{
// Get the ChapterModel for the next chapter. It must be available here;
// if not, load it immediately.
QRTextReaderChapterModel* nextChapterModel = [self chapterModelWithChapterId:self.chapterModel.chapterId+1];
if(nextChapterModel)
{
if(![nextChapterModel isPageTop]){
[nextChapterModel turnToFirstPage];
}
return [nextChapterModel curPageInfo];
}
else
{
OnlineTag* nextOnlineTag = [self onlineTagWithTag:self.onlineTag direction:QRTurnDirection_Next];
[nextOnlineTag resetProgress];
nextOnlineTag.rightParameter = CHAPTER_CUR;
nextChapterModel = [self createChapterModelWithOnlineTag:nextOnlineTag];
nextChapterModel.loadPoint = QRChapterLoadPointType_Start;
[nextChapterModel proloadChapterData];
return [nextChapterModel curPageInfo];
}

}
}

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
2
3
4
5
6
7
8
9
10
11
12
13
- (void)dragAnimationFinished:(BOOL)popSuccess toNext:(BOOL)toNext
{
...
if (toNext) // Turn to next page
{
[self.dataSource didTrunPageToNext];
}
else
{
[self.dataSource didTrunPageToPrev];
}
}

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
2
3
4
5
6
- (void)didCoverFinish{
...

[self.dataSource didTrunPageToNext];
}

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.

Refactoring TXT Engine Chapter Switching: Cover Page Turning (figure 10)
Refactoring TXT Engine Chapter Switching: Cover Page Turning (figure 11)

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
2
3
4
5
6
7
8
9
10
11
- (void)didTrunPageToPrev
{
[self invokePrevPageInsertLogic:self.chapterModel.pageIndex block:^{
if(self.isOnlineRead){
[self didTrunPageToPrevInOnlineReadMode];
}
else{
[self didTrunPageToPrevInLocalReadMode];
}
}];
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
- (void)invokePrevPageInsertLogic:(NSInteger)pageIndex block:(void(^)())block
{
if (self.insertTransitionInfo.previousPage) {
if (self.insertTransitionInfo.previousPage.integerValue == pageIndex - 1) {
QRSafelyDoBlock0(block);
[self cleanUpInsertPage];
self.accumulatePageIndex--;
[self.insertManager pageDirection:QRTurnPageDirectionToPrevious];
return;
}
if (self.insertTransitionInfo.previousPage.integerValue == pageIndex) {
[self cleanUpInsertPage];
[self.insertManager pageDirection:QRTurnPageDirectionToPrevious];
return;
}
}
self.insertTransitionInfo.nextPage = @(pageIndex);
self.insertTransitionInfo.previousPage = @(pageIndex - 1);

self.insertTransitionInfo.nextPageAd = @(self.accumulatePageIndex);
self.insertTransitionInfo.previousPageAd = @(self.accumulatePageIndex - 1);
self.insertTransitionInfo.turnPageDirection = QRTurnPageDirectionToPrevious;
if ([self canInsertAD] && [self.insertManager currentPageShouldInsertByTransitionInfo:self.insertTransitionInfo]) {
return;
}

QRSafelyDoBlock0(block);
[self cleanUpInsertPage];
}

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

  1. Changes in the following information all need to call relayoutReaderEngine to refresh the reading page:
  • Reading mode changes: 3D, smooth, no effect, cover page turning, TTS.
  • Rotation.
  • Font changes and font-size changes.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
- (void)relayoutReaderEngine    // The reading engine needs relayout when switching reading mode.
{
[self.lock lock];
[self.chapterModels enumerateKeysAndObjectsUsingBlock:
^(NSNumber * _Nonnull key, QRTextReaderChapterModel * _Nonnull model, BOOL * _Nonnull stop) {

if(nil == model.engine) return;

QRTextEngine* engine = model.engine;
QRBookMarkInfo *bookMark = [engine getBookMark];

BOOL isLandscape = UIInterfaceOrientationIsLandscape(self.curOrientation);
CGRect rect = [self getBoundRect:isLandscape isFullScreen:NO];
CGRect fullRect = [self getBoundRect:isLandscape isFullScreen:YES];

[engine setOwnRect:&rect fullRect:&fullRect];// Update drawing area.
[engine recalcPageSize];// Update page size.
[engine relayout];// Relayout.
[engine goToBookMark:bookMark];// Reposition.

if(model.onlineTag && model.onlineTag.onlineBookInfo.chapterid > 0){
// Business data must be handled after relayout, otherwise paragraphs may be lost.
[model handleTailPagePlaceholder];
}
}];
[self.lock unlock];
}

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.

  1. Clear previously laid-out page caches:
1
2
3
4
5
6
7
8
- (void)flushPageCache
{
[self.lock lock];
[self.chapterModels enumerateKeysAndObjectsUsingBlock:^(NSNumber * _Nonnull key, QRTextReaderChapterModel * _Nonnull obj, BOOL * _Nonnull stop) {
[obj flushPageCache];
}];
[self.lock unlock];
}
  1. Update all loaded TextEngine instances:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
- (void)setSetting:(QRSetting *)setting
{
_setting = setting;
[self updateEngineSetting:setting];
}

- (void)updateEngineSetting:(QRSetting*)setting
{
[self.lock lock];
[self.chapterModels enumerateKeysAndObjectsUsingBlock:^(NSNumber * _Nonnull key, QRTextReaderChapterModel * _Nonnull obj, BOOL * _Nonnull stop) {
[obj flushPageCache];
[obj.engine setSetting:setting];
}];
[self.lock unlock];
}

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
2
3
4
5
6
7
8
9
10
11
12
13
- (void)resumeEngineState
{
if(self.isPageTop){
[self scrollPageTop];
}
else if(self.isPageBottom){
[self scrollPageBottom];
}
else{
[self scrollPageUp:1];
[self scrollPageDown:1];
}
}

Later, I found that the main branch had already fixed this issue, so this change could be reverted.

Page Changes Caused by Business Data

  1. Clear rendered page caches.
  2. Update business placeholders.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// Set the placeholder area for the chapter tail page.
//
- (void)handleTailPagePlaceholder
{
// Reward
//
NSValue *placeholderForInteraction =
[self placeholderForInteraction:self.bookInfo
onlineTag:self.onlineTag];

// Author Q&A
//
NSValue *placeholderForQA =
[self placeholderForQA:self.bookInfo
onlineTag:self.onlineTag];

...

}

Clearing Cache During Page Turning

Refactoring TXT Engine Chapter Switching: Clearing Cache During Page Turning (figure 12)
  1. The current chapter keeps at most three page caches. Once there are more than three, caches are cleared.
  2. 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
2
http://git.code.oa.com/qq_reader_mobile_tech_ios/QQReader_iPhone_Proj
branch: QQReaderTXTEngine

Pitfall Notes

1. Broken Layout for “Brilliant Ideas”

Refactoring TXT Engine Chapter Switching: 1. Broken Layout for “Brilliant Ideas” (figure 13)

After investigation, I found a problem in this piece of code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
- (TextPrgf_ptr_t)_paragraphWithIdentifier:(NSInteger)paraIdentifier
paraList:(NSArray<NSNumber *> *)paraList
{
if (paraList.count <= paraIdentifier ||
paraIdentifier < 0) {
return NULL;
}

// Find the offset of the paragraph corresponding to paraIdentifier.
NSInteger paraOffset = [paraList objectAtIndex:paraIdentifier].integerValue;

// Search forward from _prgfGroup.head.
TextPrgf_ptr_t paragraph = _prgfGroup.head;
for (; paragraph != NULL;) {
if (paragraph->offset >= paraOffset &&
paraOffset <= paragraph->offset + paragraph->size) {
break;
}
paragraph = paragraph->next;
}
return paragraph;
}

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
2
3
4
5
6
7
8
// Find the offset of the paragraph corresponding to paraIdentifier.
NSInteger paraOffset = [paraList objectAtIndex:paraIdentifier].integerValue;

if(paraOffset < _prgfGroup.head->offset){
return NULL;
}

...

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
2
3
4
5
6
7
8
9
if (![self isTopPage])
{
// There is an implicit rule in txtengine's parsePrgf:lineOffset:prgfSize:policy:prgfGroup:
// it assumes one previous page of content will be cached.
// Therefore, this cache logic cannot be changed casually.
// add by zxf at 15/11/2017 for paragraph comment
//
[self cachePageImageWithIndex:currentPageIndex - 1];
}

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
2
2019-04-18 16:11:18.942489+0800 QQReaderUI[97099:5778241] end callback: 异常:0, 8192, <NSHTTPURLResponse: 0x600003c3ccc0>  { Status Code: 200, Headers {
2019-04-18 16:11:18.947396+0800 QQReaderUI[97099:5777779] progress callback: 进度 8192, 8192 , <NSMutableURLRequest: 0x600003f044f0>

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
2
2019-04-18 16:11:51.987733+0800 QQReaderUI[97099:5777779] progress callback: 进度 9216, 9216 , <NSMutableURLRequest: 0x600003f3ab10> 
2019-04-18 16:13:11.827501+0800 QQReaderUI[97099:5778430] end callback: 正常:9216, 9216, <NSHTTPURLResponse: 0x600003dc10c0> { Status Code: 200, Headers {

The cause was related to callbacks in QQHttpClient.

  • A session instance can set completionQueue, and callback blocks will execute on that queue.
  • If completionQueue is 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
2
3
4
5
6
7
8
if (!session.completionQueue){
if ([NSThread isMainThread]){
session.completionQueue = dispatch_get_main_queue();
}
else{
session.completionQueue = dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0);
}
}

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
2
3
4
5
6
7
8
9
10
11
12
if (self.downloadProgress)
{
long long totalRead = self.totalBytesRead + _partialDownloadSize;
long long expectedLength = self.response.expectedContentLength + _partialDownloadSize;

// Switch to main thread proactively here.
dispatch_async(dispatch_get_main_queue(), ^{
if (self.downloadProgress){
self.downloadProgress(length, totalRead, expectedLength);
}
});
}

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
2
// Set callback queue to main queue.
session.completionQueue = dispatch_get_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
2
3
QQReaderUI(1728,0x10ab9eb80) malloc: Heap corruption detected, free list is damaged at 0x282ecaac0
*** Incorrect guard value: 10804049344
QQReaderUI(1728,0x10ab9eb80) malloc: *** set a breakpoint in malloc_error_break to debug

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.

-------------本文结束 感谢您的阅读-------------
If this article helped you, your support encourages me to keep writing.

Title:Refactoring TXT Engine Chapter Switching

Author:lingyun

Published:2019-01-01 11:37

Updated:2026-10-08 00:23

Original link:https://tsuijunxi.github.io/en/2019/01/01/refactoring-txt-engine-chapter-switching/

License: Attribution-NonCommercial-NoDerivatives 4.0 International Please keep the original link and author when sharing.