Blitz3D+ Command Reference

MergeJsonObjectAtomic ( file$,key$,value )

Parameters

file$ - JSON object file to update; its directory must already exist

key$ - name of the member to replace

value - JSON handle whose copy becomes the member's value

Description

Replaces one member of a JSON file safely, even while other processes use it.

It reads the latest JSON object at file$, replaces the member named key$ with a copy of value, and atomically writes the object back. A short cross-process lock covers the read and write, so separate processes - a game and its launcher sharing a settings file, say - can update different members without losing each other's changes.

A missing or malformed file starts as an empty object, and existing members remain intact. Returns True on success, or 0 with FilesystemError describing the failure.


See also: SaveJsonAtomic, FilesystemError, LoadJson, FreeJson.

Example

; MergeJsonObjectAtomic Example
; -----------------------------

; A game and its launcher each update their own member of one shared
; settings file; neither update loses the other's.
Print "This example writes demo_settings.json next to itself, then deletes it."
Print "Press Y to continue, any other key to skip."
WaitKey
If KeyDown(21)

    file$="demo_settings.json"

    ; The launcher stores its window mode
    launcher=CreateJsonObject()
    mode=CreateJsonString("fullscreen")
    JsonObjectSet launcher,"mode",mode
    FreeJson mode
    If MergeJsonObjectAtomic(file$,"launcher",launcher)=0 Then RuntimeError FilesystemError()
    FreeJson launcher

    ; The game stores its volume in a different member of the same file
    game=CreateJsonObject()
    volume=CreateJsonNumber(0.8)
    JsonObjectSet game,"volume",volume
    FreeJson volume
    If MergeJsonObjectAtomic(file$,"game",game)=0 Then RuntimeError FilesystemError()
    FreeJson game

    ; Both members survive
    settings=LoadJson(file$)
    If settings=0 Then RuntimeError FilesystemError()
    Print ""
    Print "demo_settings.json now contains:"
    Print JsonStringify(settings,2)
    FreeJson settings

    DeleteFile file$
    Print ""
    Print "Demo file deleted"

Else
    Print "Skipped"
EndIf

Print ""
Print "Press any key to close the example"
WaitKey

End

Index