Building a Lightweight RunLoop, Part 1

Preface

RunLoop is a concept that has already been explained many times. Many excellent developers have written about their own understanding of it, and I have read quite a few of those articles with real admiration, for example:

Even so, I always felt that my understanding of RunLoop was still a little blurry. The veil had not been fully lifted, especially because a lot of what I knew came from hearing other people explain it.

A RunLoop is essentially a large event-driven loop. Event-driven loops exist in many languages. In pseudocode, it looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
int main(int argc, char * argv[]) {
// The program keeps running.
while (AppIsRunning) {
// Sleep and wait for a wake-up event.
id whoWakesMe = SleepForWakingUp();
// Get the wake-up event.
id event = GetEvent(whoWakesMe);
// Handle the event.
HandleEvent(event);
}
return 0;
}

Sometimes I wonder: if I tried to implement a simple, homemade version of RunLoop based on my own learning and understanding, what should it look like?

  • Since a RunLoop is, well, a loop, the first thing should be an endless loop.
  • It should also have its own event queue. Whenever an event occurs, the event is pushed into the queue, and each loop iteration takes one event out and handles it.
  • When the queue is empty, the thread running the RunLoop should sleep. When a new event arrives, that thread should be woken up. With my limited knowledge, I can only think of I/O multiplexing as the mechanism that solves this.
  • A RunLoop should distinguish Timer, Observer, Source, and other concepts.
  • …

While collecting references, I unexpectedly found a project called LightWeightRunLoop-A-Reactor-Style-NSRunLoop. It felt exactly like finding what I had been looking for. After reading it carefully, I found that its overall idea matched my own mental model quite well. So in this article, I will use its source code to analyze how a lightweight RunLoop can be implemented. Many thanks to the author, wuyunfeng.

Overall Structure

LightWeightRunLoop implements several RunLoop-related APIs, such as PerformSelector, Timer, URLConnection, LWStream, and LWPort. The goal of this article is not to explain how to use these APIs, but to understand how they are implemented internally, and use that to deepen our understanding of RunLoop.

Borrowing the author’s diagram:

Building a Lightweight RunLoop, Part 1: Overall Structure (figure 1)

LWRunLoop

How a Thread Gets an LWRunLoop Object

Every thread except the main thread can have an LWRunLoop object. It can be obtained by calling [LWRunLoop currentLWRunLoop] on the running thread:

1
2
3
4
5
6
7
8
NSThread *_lwRunLoopThread = [[NSThread alloc] initWithTarget:self selector:@selector(lightWeightRunloopThreadEntryPoint:) object:nil];

- (void)lightWeightRunloopThreadEntryPoint:(id)data
{
@autoreleasepool {
[[LWRunLoop currentLWRunLoop] run];
}
}

Internal Implementation of currentLWRunLoop

Let’s look at the internal implementation of currentLWRunLoop:

1
2
3
4
5
6
7
8
9
10
11
+ (instancetype)currentLWRunLoop
{
int result = pthread_once(& mTLSKeyOnceToken, initTLSKey);
LWRunLoop *instance = (__bridge LWRunLoop *)pthread_getspecific(mTLSKey);
if (instance == nil) {
instance = [[[self class] alloc] init];
[[NSThread currentThread] setLooper:instance];
pthread_setspecific(mTLSKey, (__bridge const void *)(instance));
}
return instance;
}

From the source code, we can see that the thread’s LWRunLoop object is stored as thread-specific data, or TSD, through pthread_setspecific and pthread_getspecific. Next, look at the initialization function of LWRunLoop. It simply initializes a message queue of type LWMessageQueue.

1
2
3
4
5
6
7
- (instancetype)init
{
if (self = [super init]) {
_queue = [LWMessageQueue defaultInstance];
}
return self;
}

How LWRunLoop Runs

Now look at the implementation of the run function in LWRunLoop:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
- (void)run
{
[self runMode:LWDefaultRunLoop];
}

#pragma mark run this loop at specific mode
- (void)runMode:(NSString *)mode
{
_currentRunLoopMode = mode;
_queue.queueRunMode = _currentRunLoopMode;
while (YES)
{
LWMessage *msg = [_queue next:_queue.queueRunMode];
[msg performSelectorForTarget];
[self necessaryInvocationForThisLoop:msg];
}
}

The idea is straightforward: in each loop iteration, take one message from the message queue and execute the corresponding event.

1
2
3
4
5
6
7
- (void)performSelectorForTarget
{
if (_mTarget == nil) { return; }
if ([_mTarget respondsToSelector:_mSelector]) {
[_mTarget performSelector:_mSelector withObject:_mArgument];
}
}
1
2
3
4
5
6
7
8
9
10
11
// Periodic LWTimer needs special handling.
- (void)necessaryInvocationForThisLoop:(LWMessage *)msg
{
if ([msg.data isKindOfClass:[LWTimer class]]) {
LWTimer *timer = msg.data;
if (timer.repeat) {
msg.when = timer.timeInterval; // must
[self postMessage:msg];
}
}
}

LWMessageQueue

How to Get LWMessageQueue

1
2
3
4
5
6
7
8
9
10
11
12
13
14
+ (instancetype)defaultInstance
{
static dispatch_once_t onceToken;
dispatch_once(&onceToken, ^{
pthread_key_create(&mThreadOneInstanceKey, threadDestructor);
});

LWMessageQueue *queue = (__bridge LWMessageQueue *)(pthread_getspecific(mThreadOneInstanceKey));
if (queue == nil) {
queue = [[LWMessageQueue alloc] init];
pthread_setspecific(mThreadOneInstanceKey, (__bridge const void *)(queue));
}
return queue;
}

Clearly, this follows the same pattern as getting LWRunLoop, so there is no need to repeat the details.

LWMessageQueue Initialization

1
2
3
4
5
6
7
8
9
10
- (instancetype)init
{
if (self = [super init])
{
_nativeRunLoop = [[LWNativeRunLoop alloc] init];
_allowStop = NO;
[self addObserver:self forKeyPath:@"queueRunMode" options:NSKeyValueObservingOptionNew | NSKeyValueObservingOptionOld context:"modechange"];
}
return self;
}

Two important things happen here:

  • It defines a LWNativeRunLoop, which is related to the kernel mechanism mentioned earlier: I/O multiplexing. LWNativeRunLoop is the core of LWRunLoop, and it is the foundation that lets this loop actually run.
  • It observes changes to the RunMode. Once the mode changes, it calls LWNativeRunLoop to wake up the kernel.
1
2
3
4
5
6
7
- (void)observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object change:(NSDictionary<NSString *,id> *)change context:(void *)context
{
if ([keyPath isEqualToString:@"queueRunMode"] && (strcmp("modechange", context) == 0 )) {
_messages = _preMessages;//runtime change
[_nativeRunLoop nativeWakeRunLoop];// should wake kernel
}
}

Enqueuing Messages in LWMessageQueue

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
- (BOOL)enqueueMessage:(LWMessage *)msg when:(NSInteger)when
{
@synchronized(self)
{
msg.when = when;
LWMessage *p = _messages;
BOOL needInterruptBolckingState = NO;

if (p == nil /*|| when == 0 */|| when < p.when) {
msg.next = p;
_messages = msg;
needInterruptBolckingState = _isCurrentLoopBlock;
} else {
LWMessage *prev = nil;
while (p != nil && p.when <= when) {
prev = p;
p = p.next;
}
msg.next = prev.next;
prev.next = msg;
needInterruptBolckingState = false;
}
if (needInterruptBolckingState) {
[_nativeRunLoop nativeWakeRunLoop];
}
}
return YES;
}

The enqueue method takes two parameters: the message itself and the time when the message should fire. The storage structure is a linked list. First it looks at the head of the list.

  1. If the head is empty, or if the new message should fire earlier than the current head, the new message becomes the head.
  2. Otherwise, it walks the linked list and finds the first message whose firing time is later than the new one, then inserts the new message before it.

Finally, if the current thread is blocked, it calls nativeWakeRunLoop to wake it up.

Dequeuing Messages from LWMessageQueue

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
- (LWMessage *)next:(NSString *)mode
{
NSInteger nextWakeTimeoutMillis = 0;
_queueRunMode = mode;
while (YES)
{
[_nativeRunLoop nativeRunLoopFor:nextWakeTimeoutMillis];
@synchronized(self)
{
NSInteger now = [LWSystemClock uptimeMillions];
LWMessage *msg = _messages;
//find the head message, assign it to _preMessages for preposition
if (msg != nil)
{
if (![self isMsgModesHit:msg.modes])
{
// can not discard, but may use in mode's changing
if (!_preMessages) {
_preMessages = msg;
notHitCurrentMsg = _preMessages;
} else {
notHitCurrentMsg.next = msg;
notHitCurrentMsg = msg;
}
_messages = msg.next;
continue;// enter into next loop
}
else
{
if (now < msg.when) {
nextWakeTimeoutMillis = msg.when - now;
}
else
{
_isCurrentLoopBlock = NO;
_messages = msg.next;
msg.next = nil;
return msg;
}
}
} else {
nextWakeTimeoutMillis = -1;
}

_isCurrentLoopBlock = YES;
}
}
}

First, it obtains the messages that need to be handled from nativeRunLoopFor.

  1. If there is no message, it marks the current thread as blocked.
  2. If the message matches the current thread’s RunMode, it checks its firing time. If the firing time is less than or equal to the current time, it removes the message from the queue and returns it. Otherwise, it simply sets nextWakeTimeoutMillis as the wake-up timeout.
  3. If the message does not match the current RunMode, it stores that message in a separate queue for messages that missed the current mode, so it can be used later when the RunMode changes.

LWNativeRunLoop: The Core

After reading the code above, it still feels like we have not touched the real core. As mentioned earlier, LWNativeRunLoop is the foundation and the key part of the whole system. So let’s analyze why it matters so much.

  • Note: before reading this part, it helps to have some background knowledge of I/O multiplexing.

LWNativeRunLoop Initialization

1
2
3
4
5
6
7
- (instancetype)init
{
if (self = [super init]) {
[self prepareLWRunLoop];
}
return self;
}
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
- (void)prepareLWRunLoop
{
int fds[2];

// Create a pipe.
int result = pipe(fds);

// fds returns two file descriptors. fds[0] is the read end, and fds[1] is the write end.
_mReadPipeFd = fds[0];
_mWritePipeFd = fds[1];

// fcntl can control open file descriptors and change their attributes.
// This block sets the two file descriptors to non-blocking mode, mainly for performance.
int rflags;
if ((rflags = fcntl(_mReadPipeFd, F_GETFL, 0)) < 0) {
NSLog(@"Failure in fcntl F_GETFL");
};
rflags |= O_NONBLOCK;
result = fcntl(_mReadPipeFd, F_SETFL, rflags);

int wflags;
if ((wflags = fcntl(_mWritePipeFd, F_GETFL, 0)) < 0) {
NSLog(@"Failure in fcntl F_GETFL");
};
wflags |= O_NONBLOCK;
result = fcntl(_mWritePipeFd, F_SETFL, wflags);

// Define a kqueue.
_kq = kqueue();

// Set the event list to monitor.
struct kevent changes[1];
EV_SET(changes, _mReadPipeFd, EVFILT_READ, EV_ADD, 0, 0, NULL);

// Call kevent. If any fd in changes is ready, the corresponding event is put into events.
// Here we do not care about events yet, so it is set to NULL.
int ret = kevent(_kq, changes, 1, NULL, 0, NULL);

// Other fields.
_fds = [[NSMutableArray alloc] init];
_requests = [[NSMutableDictionary alloc] init];
_portClients = [[NSMutableDictionary alloc] init];
}

The kqueue system has three important pieces: the struct kevent structure, the EV_SET macro, and the kevent function.

  • The struct kevent structure looks like this:
1
2
3
4
5
6
7
8
struct kevent {
uintptr_t ident; /* identifier for this event, such as the related file descriptor */
int16_t filter; /* event filter, such as EVFILT_READ, EVFILT_WRITE, EVFILT_TIMER, etc. */
uint16_t flags; /* general flags, such as EV_ADD, EV_ENABLE, EV_DELETE, etc. */
uint32_t fflags; /* filter-specific flags */
intptr_t data; /* filter-specific data */
void *udata; /* opaque user data identifier; arbitrary user data can be carried here */
};
  • EV_SET is a convenience macro used to initialize a kevent structure. Its signature is:
1
EV_SET(&kev, ident, filter, flags, fflags, data, udata);

It maps exactly to the fields of the kevent structure. The first argument is the kevent structure you want to initialize.

  • kevent is the actual function that performs I/O multiplexing. Its signature is:
1
2
3
4
5
6
int kevent(int kq, 
const struct kevent *changelist, // watch list
int nchanges, // length
struct kevent *eventlist, // list of ready events returned by kevent
int nevents, // length
const struct timespec *timeout); // timeout limit

Overall, prepareLWRunLoop mainly monitors the _mReadPipeFd file descriptor.

The Magical nativeRunLoopFor

The key method nativeRunLoopFor appears many times above. Let’s focus on it:

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
- (void)nativeRunLoopFor:(NSInteger)timeoutMillis
{
struct kevent events[MAX_EVENT_COUNT];

// Set timeout.
struct timespec *waitTime = NULL;
if (timeoutMillis == -1) {
waitTime = NULL;
} else {
waitTime = (struct timespec *)malloc(sizeof(struct timespec));
waitTime->tv_sec = timeoutMillis / 1000;
waitTime->tv_nsec = timeoutMillis % 1000 * 1000 * 1000;
}

// If any fd in the watched changes list is ready, put the corresponding event into events.
// Before an fd becomes ready, or before the timeout expires, kevent blocks this thread.
int ret = kevent(_kq, NULL, 0, events, MAX_EVENT_COUNT, waitTime);

free(waitTime);
waitTime = NULL; // avoid wild pointer

// Handle all ready events in sequence.
for (int i = 0; i < ret; i++) {
int fd = (int)events[i].ident;
int event = events[i].filter;
if (fd == _mReadPipeFd) { // for pipe read fd
if (event & EVFILT_READ) {
// If it is the watched mReadWakeFd descriptor, call nativePollRunLoop.
[self nativePollRunLoop];
} else {
continue;
}
} else if (_leader == fd){//for LWPort leader fd
if (event & EVFILT_READ) {
[self handleAccept:fd];
}
} else if (_follower == fd) {// leader -> follower
if (![self handleLeaderToFollower:fd]) {
continue;
}
} else { // follower -> leader read for LWPort follower fd, then notify leader
if (![self handleFollowerToLeader:event fd:fd]) {
continue;
}
}
}
}

For now, we only care about the _mReadPipeFd file descriptor. Once it matches, nativePollRunLoop is called:

1
2
3
4
5
6
7
8
9
- (void)nativePollRunLoop
{
char buffer[16];
ssize_t nRead;
do {
// Read data from the read end of the pipe, _mReadPipeFd.
nRead = read(_mReadPipeFd, buffer, sizeof(buffer));
} while ((nRead == -1 && errno == EINTR) || nRead == sizeof(buffer));
}

In nativePollRunLoop, the data read into buffer is simply discarded. Some people may ask: why do something that looks unnecessary?

Think about it this way: if one end of a pipe has data to read, then data must have been written to the other end:

1
2
3
4
5
6
7
- (void)nativeWakeRunLoop
{
ssize_t nWrite;
do {
nWrite = write(_mWritePipeFd, "w", 1);
} while (nWrite == -1 && errno == EINTR);
}

See it? The method name says exactly what it does.

Before a monitored file descriptor becomes ready, or before the timeout expires, kevent keeps the thread blocked, or asleep, so it no longer consumes CPU time. That means we do not care what data is actually sent or received through the pipe. What matters is that this write-and-read action directly wakes the RunLoop, allowing it to continue processing messages. With kevent handling blocking sleep, and with the pipe used here for wake-up, though other wake-up mechanisms are also possible, a thread’s RunLoop takes shape.

NSObject

Look at the postSelector here, and imagine how performSelector can be implemented:

1
2
3
4
5
6
7
- (void)postSelector:(SEL)aSelector onThread:(NSThread *)thread
withObject:(id)arg afterDelay:(NSInteger)delay
{
__weak __typeof(self) weakSelf = self;
LWRunLoop *loop = [thread looper];
[loop postTarget:weakSelf withAction:aSelector withObject:arg afterDelay:delay];
}
1
2
3
4
5
6
7
- (void)postTarget:(id)target withAction:(SEL)aSel withObject:(id)arg afterDelay:(NSInteger)delayMillis
{
NSInteger when = [LWSystemClock uptimeMillions] + delayMillis;
LWMessage *message = [[LWMessage alloc] initWithTarget:target aSel:aSel withArgument:arg at:when];
// Package target and selector directly into LWMessage, then enqueue it.
[_queue enqueueMessage:message when:when];
}

LWTimer

It follows the same pattern. Read it and you can feel the idea directly:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
+ (LWTimer *)scheduledLWTimerWithTimeInterval:(NSTimeInterval)interval target:(id)aTarget selector:(SEL)aSelector userInfo:(id)userInfo repeats:(BOOL)yesOrNo
{
if (interval <= 0) {
interval = 100;
}
LWTimer *instance = [[[self class] alloc] init];
[instance setTimeInterval:interval];
[instance setValid:YES];
[instance setUserInfo:userInfo];
[instance setRepeat:yesOrNo];
LWMessage *msg = [[LWMessage alloc] initWithTarget:aTarget aSel:aSelector withArgument:instance at:interval];
msg.data = instance;
[instance setMessage:msg];
LWRunLoop *runloop = [[NSThread currentThread] looper];
[runloop postMessage:msg];
return instance;
}
1
2
3
4
5
- (void)postMessage:(LWMessage *)msg
{
NSInteger when = msg.when + [LWSystemClock uptimeMillions];
[_queue enqueueMessage:msg when:when];
}

To Be Continued

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

Title:Building a Lightweight RunLoop, Part 1

Author:lingyun

Published:2018-06-09 16:49

Updated:2026-09-23 00:37

Original link:https://tsuijunxi.github.io/en/2018/06/09/building-a-lightweight-runloop-part-1/

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