When to use objc_memmove_collectable directly in Objective-C code?

Question

While looking for something else in header files and documentation, I recently discovered the following function prototype in <objc/objc-auto.h>:

void *objc_memmove_collectable(void *dst, const void *src, size_t size);

It's in the middle of a group of functions following a comment that says "Write barriers. Used by the compiler". These functions are used to inform the garbage collector that memory it manages has been modified so it can scan for references and not accidentally reclaim memory that should be rooted by a strong reference it doesn't know about. I know that such using __strong appropriately will nearly always cause the compiler to insert the correct function, but I've also heard Apple engineers say there are extremely rare cases when you must call such functions directly. (I believe it's when a file is not compiled as Objective-C, such as C code that writes into GC-managed memory, but I'm not positive.)

To wit, Apple's Objective-C Runtime Release Notes for Mac OS X v10.5 document states the following about this function: (last paragraph under the first heading)

"When copying memory in bulk into a garbage collected block you must use the API objc_memmove_collectable(void *dst, const void *src, size_t size)."

The function seems geared towards moving items from non-GC memory into GC memory, and email discussion archives seem to suggest that the purpose is to only trigger a single write barrier for a large block copy. (For example, 1000 individual writes with a write barrier for each, versus 1 bulk copy with a single write barrier for the entire memory region being written to.) This is one instance when it must be used, but the docs don't say anything about when it shouldn't (or needn't) be used.

For example, I have a block of memory that I allocated with NSAllocateCollectable() and NSScannedOption, and I use it as a dynamically-expanding circular buffer. If the buffer becomes full, I double its size using NSReallocateCollectable() and NSScannedOption. The portion that wraps around (between the first slot in the array and the last object in the buffer) is copied/moved to the start of the second half of the array. I then bzero() the slots where the data was copied from to avoid over-rooting the moved objects. (See lines 460-467 in this file. Yes, the code works as is — it's fully unit tested and I haven't seen any crashes since I added the __strong attribute some time ago.)

Questions:

• When is it necessary to use objc_memmove_collectable() instead of memmove() or memcpy()?
• For example, what if the source and destination are both GC-managed memory? (My memory is declared as __strong id *array; so I'd guess that the compiler inserts the barrier.)
• If it isn't necessary, will using it help/hinder GC performance? (For example, does it hold any sort of lock, or help the GC avoid having to scan manually?) Is it considered good/poor style?

---

Edit: Since memcpy and memmove don't interact with the GC at all, I was wondering why I haven't seen any crashes from the memory being collected from underneath me. My best guess at this point is that since bzero doesn't tell the GC anything either, the collector doesn't find out about the zeroed memory and the moved data until the next time it scans that whole memory block. If the collector is still counting the now-zeroed references as roots, and doesn't yet count the new memory locations, it would explain why the values don't get prematurely collected. Does this sound right?

Answer 1

I don't personally have much experience in this area, but I found an interesting discussion on the topic here.

Answer 2

I'm sure @bbum will come in with a more explanatory and definitive answer, but here's my understanding, which may not be 100% accurate.

As the header comment states, whenever you write data in bulk (i.e., with memcpy or memmove, not with =) to a scanned, GC-allocated buffer, you should always use objc_memmove_collectable to create the write barrier. The source of the data doesn't matter. memcpy doesn't have the smarts to know if you copy from scanned, GC-allocated memory to other scanned, GC-allocated memory.

I'm not sure if GC will function incorrectly without a write barrier, but it certainly would perform better. Write barriers are hints to the collector saying 'Hey! I might have written a pointer here. Can you check it for me?'. Without those, the collector would be forced to do full scans all the time.

Additionally, a single objc_memmove_collectable() is a whole lot more efficient than a bunch of implicitly write-barriered = assignments, even if you completely disregard the cost of actually writing the memory. Only one write barrier is made instead of N.