Completely revise, test and document save behaviour for MagicalRecord 2.1 #341

wants to merge 28 commits into


None yet

3 participants


This is a big change, but it's covered in unit tests and has been documented. I'll copy and paste the changes from the README:

Changes to saving

The APIs for saving have been revised to behave more consistently overall, and also to follow naming patterns present in Core Data. Extensive work has gone into adding automated tests that ensure the save methods (both new and deprecated) continue to work as expected through future updates.

MR_save has been temporarily restored to it's original state of running synchronously on the current thread, and saving to the persistent store. However, the MR_save method is marked as deprecated and will be removed in the next major release of MagicalRecord (version 3.0). You should use MR_saveToPersistentStoreAndWait if you want the same behaviour in future versions of the library.

New Methods

The following methods have been added:


  • - (void) MR_saveOnlySelfWithCompletion:(MRSaveCompletionHandler)completion;
  • - (void) MR_saveToPersistentStoreWithCompletion:(MRSaveCompletionHandler)completion;
  • - (void) MR_saveOnlySelfAndWait;
  • - (void) MR_saveToPersistentStoreAndWait;
  • - (void) MR_saveWithOptions:(MRSaveContextOptions)mask completion:(MRSaveCompletionHandler)completion;


  • + (void) saveWithBlock:(void(^)(NSManagedObjectContext *localContext))block;
  • + (void) saveWithBlock:(void(^)(NSManagedObjectContext *localContext))block completion:(MRSaveCompletionHandler)completion;
  • + (void) saveWithBlockAndWait:(void(^)(NSManagedObjectContext *localContext))block;
  • + (void) saveUsingCurrentThreadContextWithBlock:(void (^)(NSManagedObjectContext *localContext))block completion:(MRSaveCompletionHandler)completion;
  • + (void) saveUsingCurrentThreadContextWithBlockAndWait:(void (^)(NSManagedObjectContext *localContext))block;


The following methods have been deprecated in favour of newer alternatives, and will be removed in MagicalRecord 3.0:


  • - (void) MR_save;
  • - (void) MR_saveWithErrorCallback:(void(^)(NSError *error))errorCallback;
  • - (void) MR_saveInBackgroundCompletion:(void (^)(void))completion;
  • - (void) MR_saveInBackgroundErrorHandler:(void (^)(NSError *error))errorCallback;
  • - (void) MR_saveInBackgroundErrorHandler:(void (^)(NSError *error))errorCallback completion:(void (^)(void))completion;
  • - (void) MR_saveNestedContexts;
  • - (void) MR_saveNestedContextsErrorHandler:(void (^)(NSError *error))errorCallback;
  • - (void) MR_saveNestedContextsErrorHandler:(void (^)(NSError *error))errorCallback completion:(void (^)(void))completion;


  • + (void) saveWithBlock:(void(^)(NSManagedObjectContext *localContext))block;
  • + (void) saveInBackgroundWithBlock:(void(^)(NSManagedObjectContext *localContext))block;
  • + (void) saveInBackgroundWithBlock:(void(^)(NSManagedObjectContext *localContext))block completion:(void(^)(void))completion;
  • + (void) saveInBackgroundUsingCurrentContextWithBlock:(void (^)(NSManagedObjectContext *localContext))block completion:(void (^)(void))completion errorHandler:(void (^)(NSError *error))errorHandler;
tonyarnold added some commits Dec 12, 2012
@tonyarnold tonyarnold New save behaviour.
Older methods have been deprecated formally, and will be removed in the
next major release.
`MR_save` now behaves as it did pre-2.0.8.
@tonyarnold tonyarnold Use the new save methods 5616f1a
@tonyarnold tonyarnold Update existing save tests to reflect save changes. Also begin adding…
… tests for deprecated methods to ensure consistent behaviour in unmodified code.
@tonyarnold tonyarnold Update other tests to use the new save methods 4ac3b26
@tonyarnold tonyarnold Fix compilation problems under latest Xcode. c90747b
@tonyarnold tonyarnold Rename saveParentContexts methods to saveToPersistentStore f00538c
@tonyarnold tonyarnold The completion block should still run when there are no changes, with…
… a success status of NO
@tonyarnold tonyarnold Ensure that the block variables have properly named parameters c7321b6
@tonyarnold tonyarnold The root save method should always be performed synchronously (to the…
… thread it is called from)
@tonyarnold tonyarnold Update tests to use new new save methods 47f8cec
@tonyarnold tonyarnold Moar test method cleanups e85fcaf
@tonyarnold tonyarnold Changes recommended by Xcode 3161ce8
@tonyarnold tonyarnold Revised save tests d372914
@tonyarnold tonyarnold Remove xcuserdata 47a7080
@tonyarnold tonyarnold Updated gitignore ec9a919
@tonyarnold tonyarnold Add Kiwi for saner asynchronous testing bd88caa
@tonyarnold tonyarnold Flesh out tests for MagicalRecord+Actions and the NSManagedObjectCont…
…ext+MagicalSaves category
@tonyarnold tonyarnold Log when saving has finished 27c9d78
@tonyarnold tonyarnold Remove GHUnit save tests in favour of Kiwi equivalents f51fd25
@tonyarnold tonyarnold The deprecated saveWithBlock: method should do it's work on the curre…
…nt thread
@tonyarnold tonyarnold All deprecated methods in MagicalRecord+Actions are now tested for ba…
…sic function
@tonyarnold tonyarnold Clean up warnings about deprecated methods where it's legitimate 0c72ba8
@tonyarnold tonyarnold All deprecated and non-deprecated methods have tests to ensure their …
@tonyarnold tonyarnold Xcoaaaaad! b9d6969
@tonyarnold tonyarnold Update README with details of the changes in this branch 7ce2e15
bcyng commented Dec 14, 2012

i think the shorthand methods for these methods (at least saveToPersistentStoreAndWait) are missing?
(this is great stuff btw).

I'm using cocoa pods, assume these fixes will make their way there soon.

In the meantime, where should I be pulling the awesome code from?


On 14 Dec 2012, at 14:27, bcyng wrote:

i think the shorthand methods for these methods (at least saveToPersistentStoreAndWait) are missing?
(this is great stuff btw).

Reply to this email directly or view it on GitHub.


Thanks @bcyng — I'll add them later today.

@iOSDevil give me a day or two to merge this properly, and then it'll be available from the develop branch.


Closed in favour of the more concise #343

@tonyarnold tonyarnold closed this Dec 16, 2012
@tonyarnold tonyarnold deleted the tonyarnold:hotfix/save-behaviour branch Apr 21, 2013
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment