From b55ee6b0c5b70aa71d872f324d6cf2ea299fd52b Mon Sep 17 00:00:00 2001 From: Richard Frith-Macdonald Date: Thu, 11 Nov 2021 10:01:52 +0000 Subject: [PATCH] Clarify that run loop watchers are NOT retained, and are responsible for removing themselves from the run loop when they have finished watching for events. --- Headers/Foundation/NSRunLoop.h | 5 +++-- Source/GSRunLoopWatcher.h | 5 +++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/Headers/Foundation/NSRunLoop.h b/Headers/Foundation/NSRunLoop.h index b2eb5f6a6..c1d981ed8 100644 --- a/Headers/Foundation/NSRunLoop.h +++ b/Headers/Foundation/NSRunLoop.h @@ -191,8 +191,9 @@ typedef enum { /** Adds a watcher to the receiver ... the watcher is used to monitor events * of the specified type which are associted with the event handle data and * it operates in the specified run loop modes.
- * The watcher remains in place until a corresponding call to - * -removeEvent:type:forMode:all: is made. + * The watcher is not retained, but remains in place until a corresponding + * call to -removeEvent:type:forMode:all: is made. If is the watchers + * responsibility to ensure that it is removed from the run loop safely. */ - (void) addEvent: (void*)data type: (RunLoopEventType)type diff --git a/Source/GSRunLoopWatcher.h b/Source/GSRunLoopWatcher.h index 836a21ad5..3ac7b9b34 100644 --- a/Source/GSRunLoopWatcher.h +++ b/Source/GSRunLoopWatcher.h @@ -44,8 +44,9 @@ * watcher is interested in. Its meaning is system dependent. * * The 'receiver' is the object which should be told when the event - * occurs. This object is retained so that we know it will continue - * to exist and can handle a callback. + * occurs. This object is NOT retained so that we can avoid retain + * loops. It is the responsibility of the receiver to invalidate + * the watcher before it is destroyed. * * The 'type' variable indentifies the type of event watched for. * NSRunLoops [-acceptInputForMode: beforeDate: ] method MUST contain