automerge/automerge-c/README.md at querycache

Jason Kankiewicz d4a904414d Squashed commit of the following:

commit e1f8d769f4
Author: Orion Henry <orion.henry@gmail.com>
Date:   Thu Mar 10 08:53:07 2022 -0500

    update authors

commit 3e5525f1a6
Merge: f4ba1770 1c21abc5
Author: Orion Henry <orionz@users.noreply.github.com>
Date:   Wed Mar 9 14:36:29 2022 -0500

    Merge pull request #304 from jkankiewicz/c_api_exp

    Fix "fmt" workflow step violations

commit 1c21abc5a3
Author: Jason Kankiewicz <jason.kankiewicz@gmail.com>
Date:   Wed Mar 9 11:13:01 2022 -0800

    Fix CMake and Rust code formatting issues.

commit f4ba1770a9
Merge: bf1ae609 f41b30d1
Author: Orion Henry <orionz@users.noreply.github.com>
Date:   Wed Mar 9 12:05:58 2022 -0500

    Merge pull request #300 from jkankiewicz/c_api_exp

    Add unit test suites for the `AMlistSet*` and `AMmapSet*` functions

commit f41b30d118
Author: Jason Kankiewicz <jason.kankiewicz@gmail.com>
Date:   Tue Mar 8 22:08:36 2022 -0800

    Added a brief description of the `AmObjType` enum.
    Added the `AmStatus` enum to the enum docs page.

commit af7386a482
Author: Jason Kankiewicz <jason.kankiewicz@gmail.com>
Date:   Tue Mar 8 21:50:52 2022 -0800

    Added a unit test suite for the  `AMlistSet*`
    functions.

commit 1eb70c6eee
Author: Jason Kankiewicz <jason.kankiewicz@gmail.com>
Date:   Tue Mar 8 21:42:42 2022 -0800

    Added the rest of the `AMlistSet*` functions.
    Started the enum tags at `1` so they won't be
    inherently false.
    Alphabetized enum tags for the docs.
    Improved the docs.

commit 6489cba13b
Author: Jason Kankiewicz <jason.kankiewicz@gmail.com>
Date:   Tue Mar 8 18:01:46 2022 -0800

    Alphabetize functions in the docs.

commit 74c245b82d
Author: Jason Kankiewicz <jason.kankiewicz@gmail.com>
Date:   Tue Mar 8 07:54:25 2022 -0800

    Fix a typo in `AMmapSetObject()`'s documentation.

commit b2a879ba4e
Author: Jason Kankiewicz <jason.kankiewicz@gmail.com>
Date:   Tue Mar 8 06:24:22 2022 -0800

    Append missing EOF linefeed.

commit fbf0f29b66
Merge: c56d54b5 bf1ae609
Author: Jason Kankiewicz <jason.kankiewicz@gmail.com>
Date:   Tue Mar 8 01:08:12 2022 -0800

    Merge branch 'c_api_exp' of https://github.com/automerge/automerge-rs into c_api_exp

commit c56d54b565
Author: Jason Kankiewicz <jason.kankiewicz@gmail.com>
Date:   Tue Mar 8 01:07:11 2022 -0800

    Added unit test cases for the new `AMmapSet*`
    functions by @orionz.
    Moved the unit test cases for the `AMmapSet*` functions into their own
    unit test suite.

commit 7e59b55760
Author: Jason Kankiewicz <jason.kankiewicz@gmail.com>
Date:   Tue Mar 8 01:01:47 2022 -0800

    Edited the Doxygen documentation.

commit bf1ae60913
Author: Orion Henry <orion.henry@gmail.com>
Date:   Mon Mar 7 11:59:22 2022 -0500

    fmt

commit e82a7cc78e
Merge: a44e69d2 965c2d56
Author: Orion Henry <orionz@users.noreply.github.com>
Date:   Mon Mar 7 11:55:32 2022 -0500

    Merge pull request #299 from jkankiewicz/c_api_exp

    Enable unit testing of the C API

commit 965c2d56c3
Author: Jason Kankiewicz <jason.kankiewicz@gmail.com>
Date:   Mon Mar 7 06:37:36 2022 -0800

    Enable unit testing of the C API.

commit a44e69d2c7
Author: Orion Henry <orion.henry@gmail.com>
Date:   Sun Mar 6 14:00:46 2022 -0500

    remove datatype mapset

commit 88153c44e7
Merge: 41512e9c c6194e97
Author: Orion Henry <orionz@users.noreply.github.com>
Date:   Sun Mar 6 10:32:39 2022 -0500

    Merge pull request #298 from jkankiewicz/rebase_c_api_exp

    Rebase the "c_api_exp" branch on the "experiment" branch

commit c6194e9732
Merge: a2d745c8 41512e9c
Author: Jason Kankiewicz <jason.kankiewicz@gmail.com>
Date:   Sun Mar 6 01:09:56 2022 -0800

    Merge branch 'c_api_exp' into rebase_c_api_exp

commit a2d745c8d9
Author: Jason Kankiewicz <jason.kankiewicz@gmail.com>
Date:   Sun Mar 6 00:44:37 2022 -0800

    Replace the `utils::import_value` function with
    the `utils::import_scalar` function.
    Exclude `# Safety` comments from the documentation.

commit 0681e28b40
Author: Orion Henry <orion.henry@gmail.com>
Date:   Thu Mar 3 16:04:17 2022 -0500

    support new as_ref api

commit 916e23fcc2
Author: Orion Henry <orion.henry@gmail.com>
Date:   Thu Mar 3 15:56:27 2022 -0500

    fmt

commit 71cd6a1f18
Author: Orion Henry <orion.henry@gmail.com>
Date:   Thu Mar 3 15:54:38 2022 -0500

    lock data at 64 bit - no c_long

commit e00bd4c201
Author: Orion Henry <orion.henry@gmail.com>
Date:   Thu Mar 3 15:27:55 2022 -0500

    verbose

commit 39d157c554
Author: Orion Henry <orion.henry@gmail.com>
Date:   Thu Mar 3 14:56:23 2022 -0500

    clippy cleanup

commit 7f650fb8e0
Author: Jason Kankiewicz <jason.kankiewicz@gmail.com>
Date:   Wed Feb 23 02:14:06 2022 -0800

    Added Doxygen documentation generation.
    Renamed `AMDatatype` to `AmDataType`.
    Reorganized the `AmDataType` tags.
    Renamed `AMfree()` to `AMdestroy()`.
    Renamed `AMclone()` to `AMdup()`.

commit b0b803eef8
Author: Orion Henry <orion.henry@gmail.com>
Date:   Tue Feb 22 11:30:42 2022 -0500

    get simple test passing

commit cab9017ffa
Author: Orion Henry <orion.henry@gmail.com>
Date:   Wed Feb 9 15:50:44 2022 -0500

    rework to return a queriable result

commit a557e848f3
Author: Jason Kankiewicz <you@example.com>
Date:   Mon Feb 14 14:38:00 2022 -0800

    Add a CI step to run the CMake build of the C bindings for @alexjg.

commit c8c0c72f3b
Author: Jason Kankiewicz <you@example.com>
Date:   Mon Feb 14 14:09:58 2022 -0800

    Add CMake instructions for @orionz.

commit fb62c4b02a
Author: Jason Kankiewicz <you@example.com>
Date:   Thu Feb 10 23:28:54 2022 -0800

    Add CMake support.

commit 7bc3bb6850
Author: Jason Kankiewicz <you@example.com>
Date:   Thu Feb 10 22:49:53 2022 -0800

    Replace *intptr_t in C function signatures.

commit 60395a2db0
Author: Orion Henry <orion.henry@gmail.com>
Date:   Sun Feb 6 18:59:19 2022 -0500

    am_pop and am_pop_value

commit b1e88047d2
Author: Orion Henry <orion.henry@gmail.com>
Date:   Thu Feb 3 19:43:36 2022 -0500

    break the ground

commit 41512e9c78
Author: Orion Henry <orion.henry@gmail.com>
Date:   Thu Mar 3 16:04:17 2022 -0500

    support new as_ref api

commit bcee6a9623
Merge: cf98f78d 9a89db3f
Author: Orion Henry <orion.henry@gmail.com>
Date:   Thu Mar 3 15:58:19 2022 -0500

    Merge remote-tracking branch 'origin/experiment' into c_api_exp

commit cf98f78dd1
Author: Orion Henry <orion.henry@gmail.com>
Date:   Thu Mar 3 15:56:27 2022 -0500

    fmt

commit 3c1f449c5c
Author: Orion Henry <orion.henry@gmail.com>
Date:   Thu Mar 3 15:54:38 2022 -0500

    lock data at 64 bit - no c_long

commit 2c2ec0b0c5
Author: Orion Henry <orion.henry@gmail.com>
Date:   Thu Mar 3 15:27:55 2022 -0500

    verbose

commit b72b9c989a
Author: Orion Henry <orion.henry@gmail.com>
Date:   Thu Mar 3 14:56:23 2022 -0500

    clippy cleanup

commit 3ba28f91cc
Author: Jason Kankiewicz <jason.kankiewicz@gmail.com>
Date:   Wed Feb 23 02:14:06 2022 -0800

    Added Doxygen documentation generation.
    Renamed `AMDatatype` to `AmDataType`.
    Reorganized the `AmDataType` tags.
    Renamed `AMfree()` to `AMdestroy()`.
    Renamed `AMclone()` to `AMdup()`.

commit 8564e5b753
Author: Orion Henry <orion.henry@gmail.com>
Date:   Tue Feb 22 11:30:42 2022 -0500

    get simple test passing

commit 60835e6ae7
Author: Orion Henry <orion.henry@gmail.com>
Date:   Wed Feb 9 15:50:44 2022 -0500

    rework to return a queriable result

commit 89466d9e8c
Author: Jason Kankiewicz <you@example.com>
Date:   Mon Feb 14 14:38:00 2022 -0800

    Add a CI step to run the CMake build of the C bindings for @alexjg.

commit e2485bd5fd
Author: Jason Kankiewicz <you@example.com>
Date:   Mon Feb 14 14:09:58 2022 -0800

    Add CMake instructions for @orionz.

commit b5cc7dd63d
Author: Jason Kankiewicz <you@example.com>
Date:   Thu Feb 10 23:28:54 2022 -0800

    Add CMake support.

commit 685536f0cf
Author: Jason Kankiewicz <you@example.com>
Date:   Thu Feb 10 22:49:53 2022 -0800

    Replace *intptr_t in C function signatures.

commit c1c6e7bb66
Author: Orion Henry <orion.henry@gmail.com>
Date:   Sun Feb 6 18:59:19 2022 -0500

    am_pop and am_pop_value

commit e68c8d347e
Author: Orion Henry <orion.henry@gmail.com>
Date:   Thu Feb 3 19:43:36 2022 -0500

    break the ground

2022-04-19 08:35:44 -06:00

2.4 KiB

Raw Permalink Blame History

Methods we need to support

Basic management

AMcreate()
AMclone(doc)
AMfree(doc)
AMconfig(doc, key, val) // set actor
actor = get_actor(doc)

Transactions

AMpendingOps(doc)
AMcommit(doc, message, time)
AMrollback(doc)

Write

AMset{Map|List}(doc, obj, prop, value)
AMinsert(doc, obj, index, value)
AMpush(doc, obj, value)
AMdel{Map|List}(doc, obj, prop)
AMinc{Map|List}(doc, obj, prop, value)
AMspliceText(doc, obj, start, num_del, text)

Read

AMkeys(doc, obj, heads)
AMlength(doc, obj, heads)
AMvalues(doc, obj, heads)
AMtext(doc, obj, heads)

Sync

AMgenerateSyncMessage(doc, state)
AMreceiveSyncMessage(doc, state, message)
AMinitSyncState()

Save / Load

AMload(data)
AMloadIncremental(doc, data)
AMsave(doc)
AMsaveIncremental(doc)

Low Level Access

AMapplyChanges(doc, changes)
AMgetChanges(doc, deps)
AMgetChangesAdded(doc1, doc2)
AMgetHeads(doc)
AMgetLastLocalChange(doc)
AMgetMissingDeps(doc, heads)

Encode/Decode

AMencodeChange(change)
AMdecodeChange(change)
AMencodeSyncMessage(change)
AMdecodeSyncMessage(change)
AMencodeSyncState(change)
AMdecodeSyncState(change)

Open Question - Memory management

Most of these calls return one or more items of arbitrary length. Doing memory management in C is tricky. This is my proposed solution...

  // returns 1 or zero opids
  n = automerge_set(doc, "_root", "hello", datatype, value);
  if (n) {
    automerge_pop(doc, &obj, len);
  }

  // returns n values
  n = automerge_values(doc, "_root", "hello");
  for (i = 0; i<n ;i ++) {
    automerge_pop_value(doc, &value, &datatype, len);
  }

There would be one pop method per object type. Users allocs and frees the buffers. Multiple return values would result in multiple pops. Too small buffers would error and allow retry.

Formats

Actors - We could do (bytes,len) or a hex encoded string?.
ObjIds - We could do flat bytes of the ExId struct but lets do human readable strings for now - the struct would be faster but opque Heads - Might as well make it a flat buffer (n, hash, hash, ...) Changes - Put them all in a flat concatenated buffer Encode/Decode - to json strings?

2.4 KiB Raw Permalink Blame History