bson_writer_t (3) - Linux Manuals

bson_writer_t: Bulk BSON serialization Abstraction

NAME

bson_writer_t - Bulk BSON serialization Abstraction

SYNOPSIS

#include <bson.h>

typedef struct _bson_writer_t bson_writer_t;

bson_writer_t *bson_writer_new     (uint8_t           **buf,
                                    size_t             *buflen,
                                    size_t              offset,
                                    bson_realloc_func   realloc_func,
                                    void               *realloc_func_ctx);
void           bson_writer_destroy (bson_writer_t      *writer);

DESCRIPTION

The bson_writer_t API provides an abstraction for serializing many BSON documents to a single memory region. The memory region may be dynamically allocated and re-allocated as more memory is demanded. This can be useful when building network packets from a high-level language. For example, you can serialize a Python Dictionary directly to a single buffer destined for a TCP packet.

EXAMPLE

#include <bson.h>

int main (int argc, char *argv[])
{
   bson_writer_t *writer;
   uint8_t *buf = NULL;
   size_t buflen = 0;
   bson_t *doc;

   writer = bson_writer_new (&buf, &buflen, 0, bson_realloc_ctx, NULL);

   for (i = 0; i < 1000; i++) {
      bson_writer_begin (writer, &doc);
      BSON_APPEND_INT32 (&doc, "i", i);
      bson_writer_end (writer);
   }

   bson_writer_destroy (writer);

   bson_free (buf);

   return 0;
}

COLOPHON

This page is part of libbson. Please report any bugs at https://jira.mongodb.org/browse/CDRIVER.

Pages related to bson_writer_t

  • bson_writer_begin (3) - Begins writing a new document. The caller may use the bson structure to write out a new BSON document. When completed, the caller must call either bson_writer_end() or bson_writer_rollback().
  • bson_writer_destroy (3) - Cleanup after writer and release any allocated memory. Note that the buffer supplied to bson_writer_new() is NOT freed from this method. The caller is responsible for that.
  • bson_writer_end (3) - Complete writing of a bson_writer_t to the buffer supplied.
  • bson_writer_get_length (3) - Fetches the current length of the content written by the buffer (including the initial offset). This includes a partly written document currently being written.
  • bson_writer_new (3) - Creates a new instance of bson_writer_t using the buffer, length, offset, and _realloc()_ function supplied.
  • bson_writer_rollback (3) - Abort the appending of the current bson_t to the memory region managed by writer. This is useful if you detected that you went past a particular memory limit. For example, MongoDB has 48MB message limits.
  • bson_append_array (3) - The bson_append_array() function shall append child to bson using the specified key. The type of the field will be an array, but it is the responsibility of the caller to ensure that the keys of child are properly formatted with string keys such as &quot;0&quot;, &quot;1&quot;, &quot;2&quot; and so forth.
  • bson_append_array_begin (3) - The bson_append_array_begin() function shall begin appending an array field to bson. This allows for incrementally building a sub-array. Doing so will generally yield better performance as you will serialize to a single buffer. When done building the sub-array, the caller MUST call bson_append_array_end().
  • bson_append_array_end (3) - The bson_append_array_end() function shall complete the appending of an array field started with bson_append_array_begin(). child is invalid after calling this function.