Buffer c что это
Перейти к содержимому

Buffer c что это

  • автор:

C ++ — Для чего нужен как буфер, так и поток?

Хотя я прочитал о буфере и потоке, и он работает с файлами в c++, но я не знаю, что является необходимостью буфера, если поток есть, поток всегда там, чтобы перенести данные одного файла в программу, Итак, почему мы используем буферы для хранения данных (выполняя ту же задачу, что и поток) и буферизованный и небуферизованный поток.

Sharma 23 нояб. 2015, в 17:08
Поделиться
Tim B 23 нояб. 2015, в 15:22
Поделиться:

4 ответа

Лучший ответ

Ok позволяет начать с нуля, если вы хотите работать с файлами. Для этого вам нужно будет управлять тем, как данные вводятся в ваш файл и если передача данных в файл была успешной или нет, и все другие основные проблемы работы. Теперь либо вы можете управлять всем этим самостоятельно, что потребует много времени и тяжелой работы или что вы можете сделать, так это вы можете использовать поток.

Да, вы можете выделить поток для таких целей. Потоки работают с механизмом абстракции, т.е. Программисты c++ не знают, как они работают, но мы знаем только, что мы находимся на одной стороне потока (на нашей стороне программы) мы предлагаем наши данные потоку, и у него есть ответственность за передачу данных с одного конца на другой (сторона файла)

ofstream file("abc.txt"); //Here an object of output file stream is created file 

Теперь, если вы работаете с файлами, вы должны знать, что работа с файлами - очень дорогостоящая операция, т.е. требуется больше времени для доступа к файлу, чем для доступа к памяти, и нам также не нужно выполнять файловые операции каждый раз. Таким образом, программисты создали новую функцию, называемую буфером, которая является частью памяти компьютера и временно хранит данные для обработки файлов.

Предположим, что в месте чтения файла каждый раз, когда вы читаете данные, вы просто читаете какое-то место в памяти, где временно копируются все данные файла. Теперь это будет менее дорогостоящая задача, поскольку вы читаете память, а не файл.

Те потоки, у которых есть буфер для их работы, т.е. они открывают файл и по умолчанию копируют все данные файла в буфер, называются буферизованными потоками, тогда как те потоки, которые не используют какой-либо буфер, называются небуферизованными потоками.

Теперь, если вы вводите данные в буферный поток, тогда эти данные будут помещены в очередь до тех пор, пока поток не будет сброшен (сброс означает замену данных буфера на файл). Небуферизованные потоки быстрее работают (с точки зрения пользователя на одном конце потока), поскольку данные временно не хранятся в буфере и отправляются в файл по мере поступления в поток.

Переполнение буфера в глобальной области памяти

Написано много статей, постов и даже книг о переполнении буферов в стеке. Чуть меньше про переполнение буфера в куче. Но есть еще одна вещь, которую можно переполнить, и о которой пишут мало. Это буфер в глобальной области памяти (global memory). Хотя все эти проблемы сильно похожи друг на друга, тем не менее попробуем заполнить этот небольшой пробел с переполнениями буфера в глобальной памяти.

О глобальной области памяти (global memory)

Есть два места, где могут располагаться глобальные и статические переменные:

  • сегмент для инициализированных переменных и буферов
  • сегмент для неинициализированных переменных и буферов (BSS сегмент)

Те переменные, которые не инициализированы явно (то есть им не присваивается никакое значение в момент объявления), располагаются в BSS сегменте, после чего они автоматически заполняются нулями.

Вот так примерно выглядит память:

старшие адреса +-----------------------------+ | параметры командной строки | | и переменные окружения | +-----------------------------+ | стек | +-------------+---------------+ | | | | V | | | | | | | | | | ^ | | | | +-------------+---------------| | куча | +-----------------------------+ | неинициализированные данные | | (BSS сегмент) | | (заполнено нулями) | +-----------------------------+ | инициализированные данные | +-----------------------------+ | код | +----------------------------- + младшие адреса ## Пример глобального переполнения буфера Вот и простой пример, который демонстрирует переполнение буфера в глобальной области памяти: ## Как использовать переполнение буфера в глобальной памяти? Как обычно, все зависит, от того, что именно и как переполняется. Вот несколько типичных факторов: - какие данные хранятся в памяти рядом с переполняемым буфером - можем ли мы писать в память рядом с переполняемым буфером - можем ли мы читать из памяти рядом с переполняемым буфером Посмотрим на несколько примеров. ### Перезапись важных данных Ниже приведен пример приложения, которое спрашивает у пользователя пароль. Если пароль правильный, то приложение печатает секретную фразу. Вызов `strcpy` может переполнить `buffer`, если пароль содержит больше, чем 15 символов (`strcpy` добавляет \0 в конец строки). В результате мы можем переписать переменную `access`: (мы будем использовать Python для генерирования длинный строк) ``` $ gcc -g gbo.c -o gbo $ ./gbo wrong access denied $ ./gbo `python3 -c "print('x' * 16 + 'y')"` this is a secret ``` Это происходит, потому что `buffer` и `access` находятся в сегменте для неинициализированных данных. Более того, в памяти `access` располагается сразу после `buffer`. На самом деле, расположение эти переменных в памяти может быть и другим, потому что порядок следования глобальных переменных не определен. Поэтому код выше может быть и неуязвим в некоторых случаях (это может зависеть, например, от компилятора). Здесь есть еще одна интересная деталь. Проблема уйдет, если мы явно инициализируем переменную `access` при ее объявлении: ``` char access = 'n'; ``` В этом случае компилятор разместит переменную `access` в сегмент для инициализированных переменных, который обычно идет до сегмента для неинициализированных данных. В результате переполнение `buffer` не будет приводить к перезаписи переменной `access`. ### Перезапись объектов в куче или простой segfault Обычно куча начинается где-то после BSS сегмента. Но фактический адрес начала кучи может быть разным. Посмотрим на вот такой код: Сначала определяем `buffer` в глобальной области памяти и `allocated` в куче. Потом копируем строку "test" в буфер `allocated`. Дальше печатаем адреса и содержимое буферов. И в самом конце копируем первый параметр командной строки в глобальный буфер и опять печатаем `allocated`. На моем Линуксе следующая команда вызывает segfault: ``` $ ./gbo `python3 -c "print('x' * 2**12)"` buffer address = 0x601070 allocated address = 0x773010 allocated address - buffer address = 1515424 allocated (before) = test Segmentation fault (core dumped) ``` Здесь мы пытаемся запихать в `buffer` строку, которая состоит из 4096 символов 'x', и которая его успешно переполняет. Буфер `allocated` располагается по адресу 0x773010 (вообще этот адрес меняется от запуска к запуску из-за динамического выделения памяти). Заметим, что разница между адресами намного больше (1515424), чем 4096. В результате мы получаем segfault, потому что мы пытаемся записать что-то по некорректному адресу. Не очень похоже, что есть возможность перезаписывать объекты в куче, если мы можем переполнить буфер в глобальной области памяти. Но всегда можно уронить приложение. ### Перезапись указателя на функцию в глобальной области памяти Указатель на функцию просто содержит адрес этой функции в памяти. Указатель на функцию может быть использовать для вызова этой функции. Все довольно просто. Вот пример перезаписи указателя на функцию: Этот код похож на тот, что мы рассмотрели ранее, только здесь мы балуемся с указателем на функцию. Сначала указатель на функцию `func` не инициализирован. Затем мы помещаем в него адрес функции `do_something`. Если пароль правильный, то помещаем в указатель адрес функции `print_secret`. И наконец с помощью указателя `func` мы вызываем функцию, на которую он указывает. Вызов `strcpy` может переполнить `buffer` , если параметр командной строки больше 15ти символов (не забываем, что `strcpy` добавляет \0 в конец строки). Так как и `func`, и `buffer` не инициализированы сразу, то они оба живут в сегменте для неинициализированных данных. В результате чего мы и может перезаписать указатель `func`: ``` $ gcc -g gbo.c -o gbo $ ./gbo `python3 -c "print('w' * 256)"` Segmentation fault (core dumped) ``` Мы только что записали в `func` адрес 0x77777777 (0x77 это ASCII-код символа 'w'). Далее наше наивное приложение попыталось вызвать функцию, которая располагается по этому адресу. Так как этот адрес некорректный, мы получили segfault. Но простое падение приложение это не интересно. Интереснее заставить приложение выполнить то, что мы хотим. Предположим, что мы хотим вызвать функцию `print_secret` , но мы не знаем пароля. Сначала выясним адрес функции `print_secret`. GDB поможет нам с этим: ``` $ gdb --args ./gbo test Reading symbols from ./gbo. done. (gdb) break gbo.c:36 Breakpoint 1 at 0x40068c: file gbo.c, line 36. (gdb) run Starting program: /home/artem/tmp/gbo test Breakpoint 1, main (argc=2, argv=0x7fffffffdcf8) at gbo.c:36 36 func(); (gdb) p func $1 = (void (*)(void)) 0x7777777777777777 (gdb) p print_secret $2 = 0x400607 (gdb) quit ``` Теперь мы знаем, что адрес функции `print_secret` это 0x400607. Дальше нам нужно передать приложению такую строку, чтобы оно записало адрес 0x400607 в указатель `func`. Для этого надо учесть следующее: - надо записать 16 байтов, чтобы заполнить `buffer` - помним, что мы в 64-битной системе, поэтому нам надо 8 байтов для перезаписи указателя `func` - помним, что мы в little-endian системе, так что вместо 0x400607 нужно писать 0x070640 Следующая команда заставляет приложение вызвать функцию `print_secret`, даже если предоставлен неправильный пароль: ``` $ ./gbo `python3 -c "print('w' * 16 + '\x00\x00\x00\x00\x00\x07\x06\x40')"` this is a secret ``` ### Чтение конфиденциальных данных из глобальной памяти Наверное каждый слышал про Heartbleed и OpenSSL. Это прекрасный пример так называемой "buffer overread" уязвимости, которая означает, что хитрый злоумышленник может читать память за пределами буфера. В случае с Heartbleed, коварный злоумышленник мог читать конфиденциальные данные из кучи. Подобные уязвимости возможны и с глобальной памятью, где тоже могут храниться всякие конфиденциальные данные. Вот простой пример уязвимого приложения: Приложение получает количество символов, которое надо напечатать. Оно копирует обозначенное количество байтов из глобального буфера `public` в локальный `buffer`. Дальше оно печатает все строки в `buffer`. Если количество запрашиваемых символов больше, чем размер `public`, то приложение будет послушно читать память за пределами `public`. Это приводит к чтению буфера `secret`, который следует сразу же за `public` в сегменте для неинициализированных данных. В результате содержимое `secret` печатается на экран. ## Как предотвратить переполнение буфера Все тоже самое, что и в случае с переполнениями в стеке и куче. Разница между ними не большая. Разработчикам следует мыть руки с мылом перед работой с памятью и быть с ней очень внимательными. Использование мозга и трепетный подход к программированию может помочь избежать подобных проблем. Разумные сроки и отсутствие постоянного аврала и штурмовщины создают положительные условия для предотвращения переполнений буферов (дорогие менеджеры, вы можете вашим программистам). Code review, статические и динамические анализаторы также помогают вовремя отловить возникшие проблемы.
  • Artem Smotrakov
  • artem.smotrakov@gmail.com

Кольцевой FIFO буфер в языке Си

Фундаментальная вещь организации любой цифровой системы — буферы. Они используются везде: память, шины, сети, алгоритмы. Рассмотрим реализацию такого буфера на языке Си для использования в своих проектах.

Function Reference

Как обычно, методы возвращают статусы:

typedef enum RINGBUF_STATUS < RINGBUF_OK, ///< Успех RINGBUF_ERR, ///< Ошибка RINGBUF_PARAM_ERR, ///< Ошибка в аргументах RINGBUF_OVERFLOW, ///< Попытка записи >буфера > RINGBUF_STATUS;

Сам буфер инициализируется через структуру:

typedef struct RINGBUF_t < u8_t *buf; ///< Указатель на буфер volatile size_t tail; ///< Точка чтения [ячейка] volatile size_t head; ///< Точка записи [ячейка] volatile size_t size; ///< Размер буфера [ячейка] volatile size_t cell_size; ///< Размер одной ячейки [байт] >RINGBUF_t;

Описание методов:
(Описание аргументов представлено в DoxyGen-формате в .с-файле)

/* Главные методы */ // Инициализация буфера RINGBUF_STATUS RingBuf_Init(void *buf, u16_t size, size_t cellsize, RINGBUF_t *rb); // Очистка буфера RINGBUF_STATUS RingBuf_Clear(RINGBUF_t *rb); // Считать количество доступных для чтения ячеек RINGBUF_STATUS RingBuf_Available(u16_t *len, RINGBUF_t *rb); /* Запись */ // Записать 1 байт в буфер RINGBUF_STATUS RingBuf_BytePut(const u8_t data, RINGBUF_t *rb); // Записать 1 ячейку заданного размера в буфер RINGBUF_STATUS RingBuf_CellPut(const void *data, RINGBUF_t *rb); // Записать произвольное количество данных в буфер RINGBUF_STATUS RingBuf_DataPut(const void *data, u16_t len, RINGBUF_t *rb); /* Чтение (Считывание и очистка) */ // Прочесть 1 байт RINGBUF_STATUS RingBuf_ByteRead(u8_t *data, RINGBUF_t *rb); // Прочесть 1 ячейку заданного размера RINGBUF_STATUS RingBuf_CellRead(void *data, RINGBUF_t *rb); // Прочесть произвольное количество данных RINGBUF_STATUS RingBuf_DataRead(void *data, u16_t len, RINGBUF_t *rb); /* Просмотр (Считывание без очистки) */ // Подсмотреть 1 байт RINGBUF_STATUS RingBuf_ByteWatch(u8_t *data, RINGBUF_t *rb); // Подсмотреть 1 ячейку заданного размера RINGBUF_STATUS RingBuf_CellWatch(void *data, RINGBUF_t *rb); // Подсмотреть произвольное количество данных RINGBUF_STATUS RingBuf_DataWatch(void *data, u16_t len, RINGBUF_t *rb);

Принцип кольцевого буфера

Кольцевые буферы по умолчанию строятся по топологии “FIFO”.

Это один из способов организации данных. Ещё он называется очередью.
FIFO расшифровывается как “First Input — First Output”. Первым вошёл — первым вышел.

Другой способ — “LIFO” или стек. Last input, first output — последним вошёл ­­— первым вышел.
Практически применение закольцованности для LIFO бессмысленно, по крайней мере я ни разу такого не встречал.
LIFO применяется в алгоритмах, например DFS.
Также стек применяется для низкоуровневых задач, таких как стек вызовов подпрограмм или прерываний.
Гипотетически, все нижеописанные выкладки и рассуждения подходят для реализации LIFO.

Суть FIFO в том, что те данные, которые первыми записали, первыми и должны быть считаны.
Проще представить это схематично.

Представим себе мусоропровод. Это такая труба для мусора в многоквартирных домах, с люками на каждом этаже.
(Такую аналогию я в сети ещё не встречал)
В начальный момент времени он пуст. Мы кинули туда мешок, то есть некоторый пакет данных.

Кольцевой FIFO буфер в языке Си

Остальные жильцы в течение дня накидали ещё мусора. Образовалась горочка. Ну, предположим, 5 пакетов. Пришла уборщица, открыла люк, мешки посыпались. Какой мешок выпадет первым? Правильно. Наш первый. Далее вывалится мешок жильца №2, затем жильца №3, и так далее…

Кольцевой FIFO буфер в языке Си

А теперь представим, что уборщица вовремя не собирает мусор, труба мусоропровода забилась. Вызвали аварийную бригаду из ЖЭКа, доблестный Жека прочистил трубу, она вновь доступна для жильцов.
Это и есть закольцованность FIFO буфера. Некоторое допущение, которое позволяет потеряться данным, но которое всегда оставляет возможность для записи новых, релевантных данных.

FIFO блокируется при переполнении, в отличие от кольцевого буфера

Какое этому применение?
В любых асинхронных процессах, например для шины USB, или для приёма данных по UART, требуется своевременно обрабатывать принятые данные.
Так как посылки могут прийти в любой момент, а контроллер в это время может заниматься более приоритетными задачами, вызывается быстрое прерывание, которое лишь перекладывает данные из одного буфера в другой.
Таким образом, когда придёт время обработать шину, программа обратится к долгосрочному буферу, который обеспечит обработку данных так, как будто они были получены в реальном времени.

Реализация в языке

Читатель может задаться вопросом: зачем же прописывать всё это руками, если это есть почти в любом языке?
Ответ прост: в языке Си, основном для разработки для микроконтроллеров, всего этого нет.
На мой взгляд, для создания высокоэффективных систем, в целях максимальной оптимизации, разработчик обязан “прощупать” всё своими руками. Тем более, что подобные вещи пишутся один раз, и применяются во всех последующих проектах.
Это есть в том же C++, но там подобные структуры — динамические. Для нашей крохотной относительно ПК ОЗУ динамическая память — зло злющее.

Сначала поймём, как представить эту очередь в памяти. Естественно, делать это будем с помощью массива. Он будет хранилищем данных. Создадим ещё 2 переменные ­— некоторые счётчики. В них будут лежать индексы чтения и записи.

Кольцевой FIFO буфер в языке Си

Создадим также методы. Основные:

  • Чтение
  • Запись
  • Размер (ячеек для чтения)
  • Очистка

Так как буферов может использоваться несколько, используем структурный подход. В структуре будут лежать:

  • Массив данных — а лучше указатель на выделенное пространство памяти
  • Размер этого массива
  • Точка записи или head
  • Точка чтения или tail

В каждый метод будем передавать указатель на instance структуры. То есть сами методы будут реализовывать лишь логику.

Начнём с размера. Количество доступных для чтения ячеек считается так: tail-head. Всё просто. Самое главное — проверить, если tail > head, то нужно учесть ещё и размер всего буфера.

Кольцевой FIFO буфер в языке Си

Операция записи: положили данные, начиная с head, прибавили head.

Кольцевой FIFO буфер в языке Си

Операция чтения: считали данные, начиная с tail, прибавили tail.

Кольцевой FIFO буфер в языке Си

Теперь можно писать саму реализацию. Пример можно найти на GitHub.
В своём фирменном стиле я использовал ещё и статусы, но в вашем коде это совершенно необязательно.

Благодарность можно оставить тут.

Ссылки

  1. https://www.geeksforgeeks.org/fifo-first-in-first-out-approach-in-programming/
  2. https://cdeblog.ru/simple-ring-buffer
  3. https://livepcwiki.ru/wiki/Circular_buffer

Protocol Buffer Basics: C++

This isn’t a comprehensive guide to using protocol buffers in C++. For more detailed reference information, see the Protocol Buffer Language Guide (proto2), the Protocol Buffer Language Guide (proto3), the C++ API Reference, the C++ Generated Code Guide, and the Encoding Reference.

The Problem Domain

The example we’re going to use is a very simple “address book” application that can read and write people’s contact details to and from a file. Each person in the address book has a name, an ID, an email address, and a contact phone number.

How do you serialize and retrieve structured data like this? There are a few ways to solve this problem:

  • The raw in-memory data structures can be sent/saved in binary form. Over time, this is a fragile approach, as the receiving/reading code must be compiled with exactly the same memory layout, endianness, etc. Also, as files accumulate data in the raw format and copies of software that are wired for that format are spread around, it’s very hard to extend the format.
  • You can invent an ad-hoc way to encode the data items into a single string – such as encoding 4 ints as “12:3:-23:67”. This is a simple and flexible approach, although it does require writing one-off encoding and parsing code, and the parsing imposes a small run-time cost. This works best for encoding very simple data.
  • Serialize the data to XML. This approach can be very attractive since XML is (sort of) human readable and there are binding libraries for lots of languages. This can be a good choice if you want to share data with other applications/projects. However, XML is notoriously space intensive, and encoding/decoding it can impose a huge performance penalty on applications. Also, navigating an XML DOM tree is considerably more complicated than navigating simple fields in a class normally would be.

Instead of these options, you can use protocol buffers. Protocol buffers are the flexible, efficient, automated solution to solve exactly this problem. With protocol buffers, you write a .proto description of the data structure you wish to store. From that, the protocol buffer compiler creates a class that implements automatic encoding and parsing of the protocol buffer data with an efficient binary format. The generated class provides getters and setters for the fields that make up a protocol buffer and takes care of the details of reading and writing the protocol buffer as a unit. Importantly, the protocol buffer format supports the idea of extending the format over time in such a way that the code can still read data encoded with the old format.

Where to Find the Example Code

The example code is included in the source code package, under the “examples” directory.

Defining Your Protocol Format

To create your address book application, you’ll need to start with a .proto file. The definitions in a .proto file are simple: you add a message for each data structure you want to serialize, then specify a name and a type for each field in the message. Here is the .proto file that defines your messages, addressbook.proto .

syntax = "proto2";   package tutorial;   message Person   optional string name = 1;  optional int32 id = 2;  optional string email = 3;   enum PhoneType   PHONE_TYPE_UNSPECIFIED = 0;  PHONE_TYPE_MOBILE = 1;  PHONE_TYPE_HOME = 2;  PHONE_TYPE_WORK = 3;  >   message PhoneNumber   optional string number = 1;  optional PhoneType type = 2 [default = PHONE_TYPE_HOME];  >   repeated PhoneNumber phones = 4;  >   message AddressBook   repeated Person people = 1;  > 

As you can see, the syntax is similar to C++ or Java. Let’s go through each part of the file and see what it does.

The .proto file starts with a package declaration, which helps to prevent naming conflicts between different projects. In C++, your generated classes will be placed in a namespace matching the package name.

Next, you have your message definitions. A message is just an aggregate containing a set of typed fields. Many standard simple data types are available as field types, including bool , int32 , float , double , and string . You can also add further structure to your messages by using other message types as field types – in the above example the Person message contains PhoneNumber messages, while the AddressBook message contains Person messages. You can even define message types nested inside other messages – as you can see, the PhoneNumber type is defined inside Person . You can also define enum types if you want one of your fields to have one of a predefined list of values – here you want to specify that a phone number can be one of the following phone types: PHONE_TYPE_MOBILE , PHONE_TYPE_HOME , or PHONE_TYPE_WORK .

The " = 1", " = 2" markers on each element identify the unique field number that field uses in the binary encoding. Field numbers 1-15 require one less byte to encode than higher numbers, so as an optimization you can decide to use those numbers for the commonly used or repeated elements, leaving field numbers 16 and higher for less-commonly used optional elements. Each element in a repeated field requires re-encoding the field number, so repeated fields are particularly good candidates for this optimization.

Each field must be annotated with one of the following modifiers:

  • optional : the field may or may not be set. If an optional field value isn’t set, a default value is used. For simple types, you can specify your own default value, as we’ve done for the phone number type in the example. Otherwise, a system default is used: zero for numeric types, the empty string for strings, false for bools. For embedded messages, the default value is always the “default instance” or “prototype” of the message, which has none of its fields set. Calling the accessor to get the value of an optional (or required) field which has not been explicitly set always returns that field’s default value.
  • repeated : the field may be repeated any number of times (including zero). The order of the repeated values will be preserved in the protocol buffer. Think of repeated fields as dynamically sized arrays.
  • required : a value for the field must be provided, otherwise the message will be considered “uninitialized”. If libprotobuf is compiled in debug mode, serializing an uninitialized message will cause an assertion failure. In optimized builds, the check is skipped and the message will be written anyway. However, parsing an uninitialized message will always fail (by returning false from the parse method). Other than this, a required field behaves exactly like an optional field.
Important

Required Is Forever You should be very careful about marking fields as required . If at some point you wish to stop writing or sending a required field, it will be problematic to change the field to an optional field – old readers will consider messages without this field to be incomplete and may reject or drop them unintentionally. You should consider writing application-specific custom validation routines for your buffers instead. Within Google, required fields are strongly disfavored; most messages defined in proto2 syntax use optional and repeated only. (Proto3 does not support required fields at all.)

You’ll find a complete guide to writing .proto files – including all the possible field types – in the Protocol Buffer Language Guide. Don’t go looking for facilities similar to class inheritance, though – protocol buffers don’t do that.

Compiling Your Protocol Buffers

Now that you have a .proto , the next thing you need to do is generate the classes you’ll need to read and write AddressBook (and hence Person and PhoneNumber ) messages. To do this, you need to run the protocol buffer compiler protoc on your .proto :

  1. If you haven’t installed the compiler, download the package and follow the instructions in the README.
  2. Now run the compiler, specifying the source directory (where your application’s source code lives – the current directory is used if you don’t provide a value), the destination directory (where you want the generated code to go; often the same as $SRC_DIR ), and the path to your .proto . In this case, you…:

protoc -I=$SRC_DIR --cpp_out=$DST_DIR $SRC_DIR/addressbook.proto 

This generates the following files in your specified destination directory:

  • addressbook.pb.h , the header which declares your generated classes.
  • addressbook.pb.cc , which contains the implementation of your classes.

The Protocol Buffer API

Let’s look at some of the generated code and see what classes and functions the compiler has created for you. If you look in addressbook.pb.h , you can see that you have a class for each message you specified in addressbook.proto . Looking closer at the Person class, you can see that the compiler has generated accessors for each field. For example, for the name , id , email , and phones fields, you have these methods:

 // name  inline bool has_name() const;  inline void clear_name();  inline const ::std::string& name() const;  inline void set_name(const ::std::string& value);  inline void set_name(const char* value);  inline ::std::string* mutable_name();   // id  inline bool has_id() const;  inline void clear_id();  inline int32_t id() const;  inline void set_id(int32_t value);   // email  inline bool has_email() const;  inline void clear_email();  inline const ::std::string& email() const;  inline void set_email(const ::std::string& value);  inline void set_email(const char* value);  inline ::std::string* mutable_email();   // phones  inline int phones_size() const;  inline void clear_phones();  inline const ::google::protobuf::RepeatedPtrField ::tutorial::Person_PhoneNumber >& phones() const;  inline ::google::protobuf::RepeatedPtrField ::tutorial::Person_PhoneNumber >* mutable_phones();  inline const ::tutorial::Person_PhoneNumber& phones(int index) const;  inline ::tutorial::Person_PhoneNumber* mutable_phones(int index);  inline ::tutorial::Person_PhoneNumber* add_phones(); 

As you can see, the getters have exactly the name as the field in lowercase, and the setter methods begin with set_ . There are also has_ methods for each singular (required or optional) field which return true if that field has been set. Finally, each field has a clear_ method that un-sets the field back to its empty state.

While the numeric id field just has the basic accessor set described above, the name and email fields have a couple of extra methods because they’re strings – a mutable_ getter that lets you get a direct pointer to the string, and an extra setter. Note that you can call mutable_email() even if email is not already set; it will be initialized to an empty string automatically. If you had a repeated message field in this example, it would also have a mutable_ method but not a set_ method.

Repeated fields also have some special methods – if you look at the methods for the repeated phones field, you’ll see that you can

  • check the repeated field’s _size (in other words, how many phone numbers are associated with this Person ).
  • get a specified phone number using its index.
  • update an existing phone number at the specified index.
  • add another phone number to the message which you can then edit (repeated scalar types have an add_ that just lets you pass in the new value).

For more information on exactly what members the protocol compiler generates for any particular field definition, see the C++ generated code reference.

Enums and Nested Classes

The generated code includes a PhoneType enum that corresponds to your .proto enum. You can refer to this type as Person::PhoneType and its values as Person::PHONE_TYPE_MOBILE , Person::PHONE_TYPE_HOME , and Person::PHONE_TYPE_WORK (the implementation details are a little more complicated, but you don’t need to understand them to use the enum).

The compiler has also generated a nested class for you called Person::PhoneNumber . If you look at the code, you can see that the “real” class is actually called Person_PhoneNumber , but a typedef defined inside Person allows you to treat it as if it were a nested class. The only case where this makes a difference is if you want to forward-declare the class in another file – you cannot forward-declare nested types in C++, but you can forward-declare Person_PhoneNumber .

Standard Message Methods

Each message class also contains a number of other methods that let you check or manipulate the entire message, including:

  • bool IsInitialized() const; : checks if all the required fields have been set.
  • string DebugString() const; : returns a human-readable representation of the message, particularly useful for debugging.
  • void CopyFrom(const Person& from); : overwrites the message with the given message’s values.
  • void Clear(); : clears all the elements back to the empty state.

These and the I/O methods described in the following section implement the Message interface shared by all C++ protocol buffer classes. For more info, see the complete API documentation for Message .

Parsing and Serialization

Finally, each protocol buffer class has methods for writing and reading messages of your chosen type using the protocol buffer binary format. These include:

  • bool SerializeToString(string* output) const; : serializes the message and stores the bytes in the given string. Note that the bytes are binary, not text; we only use the string class as a convenient container.
  • bool ParseFromString(const string& data); : parses a message from the given string.
  • bool SerializeToOstream(ostream* output) const; : writes the message to the given C++ ostream .
  • bool ParseFromIstream(istream* input); : parses a message from the given C++ istream .

These are just a couple of the options provided for parsing and serialization. Again, see the Message API reference for a complete list.

Important

Protocol Buffers and Object Oriented Design Protocol buffer classes are basically data holders (like structs in C) that don’t provide additional functionality; they don’t make good first class citizens in an object model. If you want to add richer behavior to a generated class, the best way to do this is to wrap the generated protocol buffer class in an application-specific class. Wrapping protocol buffers is also a good idea if you don’t have control over the design of the .proto file (if, say, you’re reusing one from another project). In that case, you can use the wrapper class to craft an interface better suited to the unique environment of your application: hiding some data and methods, exposing convenience functions, etc. You should never add behavior to the generated classes by inheriting from them. This will break internal mechanisms and is not good object-oriented practice anyway.

Writing a Message

Now let’s try using your protocol buffer classes. The first thing you want your address book application to be able to do is write personal details to your address book file. To do this, you need to create and populate instances of your protocol buffer classes and then write them to an output stream.

Here is a program which reads an AddressBook from a file, adds one new Person to it based on user input, and writes the new AddressBook back out to the file again. The parts which directly call or reference code generated by the protocol compiler are highlighted.

#include #include #include #include "addressbook.pb.h"  using namespace std;  // This function fills in a Person message based on user input.  void PromptForAddress(tutorial::Person* person)   cout  <"Enter person ID number: ";  int id;  cin >> id;  person->set_id(id);  cin.ignore(256, '\n');   cout  <"Enter name: ";  getline(cin, *person->mutable_name());   cout  <"Enter email address (blank for none): ";  string email;  getline(cin, email);  if (!email.empty())   person->set_email(email);  >   while (true)   cout  <"Enter a phone number (or leave blank to finish): ";  string number;  getline(cin, number);  if (number.empty())   break;  >   tutorial::Person::PhoneNumber* phone_number = person->add_phones();  phone_number->set_number(number);   cout  <"Is this a mobile, home, or work phone? ";  string type;  getline(cin, type);  if (type == "mobile")   phone_number->set_type(tutorial::Person::PHONE_TYPE_MOBILE);  > else if (type == "home")   phone_number->set_type(tutorial::Person::PHONE_TYPE_HOME);  > else if (type == "work")   phone_number->set_type(tutorial::Person::PHONE_TYPE_WORK);  > else   cout  <"Unknown phone type. Using default."  <endl;  >  > >  // Main function: Reads the entire address book from a file, // adds one person based on user input, then writes it back out to the same // file.  int main(int argc, char* argv[])   // Verify that the version of the library that we linked against is  // compatible with the version of the headers we compiled against.  GOOGLE_PROTOBUF_VERIFY_VERSION;   if (argc != 2)   cerr  <"Usage: "  <argv[0]  <" ADDRESS_BOOK_FILE"  <endl;  return -1;  >   tutorial::AddressBook address_book;     // Read the existing address book.  fstream input(argv[1], ios::in | ios::binary);  if (!input)   cout  <argv[1]  <": File not found. Creating a new file."  <endl;  > else if (!address_book.ParseFromIstream(&input))   cerr  <"Failed to parse address book."  <endl;  return -1;  >  >   // Add an address.  PromptForAddress(address_book.add_people());     // Write the new address book back to disk.  fstream output(argv[1], ios::out | ios::trunc | ios::binary);  if (!address_book.SerializeToOstream(&output))   cerr  <"Failed to write address book."  <endl;  return -1;  >  >   // Optional: Delete all global objects allocated by libprotobuf.  google::protobuf::ShutdownProtobufLibrary();   return 0; > 

Notice the GOOGLE_PROTOBUF_VERIFY_VERSION macro. It is good practice – though not strictly necessary – to execute this macro before using the C++ Protocol Buffer library. It verifies that you have not accidentally linked against a version of the library which is incompatible with the version of the headers you compiled with. If a version mismatch is detected, the program will abort. Note that every .pb.cc file automatically invokes this macro on startup.

Also notice the call to ShutdownProtobufLibrary() at the end of the program. All this does is delete any global objects that were allocated by the Protocol Buffer library. This is unnecessary for most programs, since the process is just going to exit anyway and the OS will take care of reclaiming all of its memory. However, if you use a memory leak checker that requires that every last object be freed, or if you are writing a library which may be loaded and unloaded multiple times by a single process, then you may want to force Protocol Buffers to clean up everything.

Reading a Message

Of course, an address book wouldn’t be much use if you couldn’t get any information out of it! This example reads the file created by the above example and prints all the information in it.

#include #include #include #include "addressbook.pb.h"  using namespace std;  // Iterates though all people in the AddressBook and prints info about them.  void ListPeople(const tutorial::AddressBook& address_book)   for (int i = 0; i  address_book.people_size(); i++)   const tutorial::Person& person = address_book.people(i);   cout  <"Person ID: "  <person.id()  <endl;  cout  <" Name: "  <person.name()  <endl;  if (person.has_email())   cout  <" E-mail address: "  <person.email()  <endl;  >   for (int j = 0; j  person.phones_size(); j++)   const tutorial::Person::PhoneNumber& phone_number = person.phones(j);   switch (phone_number.type())   case tutorial::Person::PHONE_TYPE_MOBILE:  cout  <" Mobile phone #: ";  break;  case tutorial::Person::PHONE_TYPE_HOME:  cout  <" Home phone #: ";  break;  case tutorial::Person::PHONE_TYPE_WORK:  cout  <" Work phone #: ";  break;  >  cout  <phone_number.number()  <endl;  >  > >  // Main function: Reads the entire address book from a file and prints all // the information inside.  int main(int argc, char* argv[])   // Verify that the version of the library that we linked against is  // compatible with the version of the headers we compiled against.  GOOGLE_PROTOBUF_VERIFY_VERSION;   if (argc != 2)   cerr  <"Usage: "  <argv[0]  <" ADDRESS_BOOK_FILE"  <endl;  return -1;  >   tutorial::AddressBook address_book;     // Read the existing address book.  fstream input(argv[1], ios::in | ios::binary);  if (!address_book.ParseFromIstream(&input))   cerr  <"Failed to parse address book."  <endl;  return -1;  >  >   ListPeople(address_book);   // Optional: Delete all global objects allocated by libprotobuf.  google::protobuf::ShutdownProtobufLibrary();   return 0; > 

Extending a Protocol Buffer

Sooner or later after you release the code that uses your protocol buffer, you will undoubtedly want to “improve” the protocol buffer’s definition. If you want your new buffers to be backwards-compatible, and your old buffers to be forward-compatible – and you almost certainly do want this – then there are some rules you need to follow. In the new version of the protocol buffer:

  • you must not change the field numbers of any existing fields.
  • you must not add or delete any required fields.
  • you may delete optional or repeated fields.
  • you may add new optional or repeated fields but you must use fresh field numbers (that is, field numbers that were never used in this protocol buffer, not even by deleted fields).

(There are some exceptions to these rules, but they are rarely used.)

If you follow these rules, old code will happily read new messages and simply ignore any new fields. To the old code, optional fields that were deleted will simply have their default value, and deleted repeated fields will be empty. New code will also transparently read old messages. However, keep in mind that new optional fields will not be present in old messages, so you will need to either check explicitly whether they’re set with has_ , or provide a reasonable default value in your .proto file with [default = value] after the field number. If the default value is not specified for an optional element, a type-specific default value is used instead: for strings, the default value is the empty string. For booleans, the default value is false. For numeric types, the default value is zero. Note also that if you added a new repeated field, your new code will not be able to tell whether it was left empty (by new code) or never set at all (by old code) since there is no has_ flag for it.

Optimization Tips

The C++ Protocol Buffers library is extremely heavily optimized. However, proper usage can improve performance even more. Here are some tips for squeezing every last drop of speed out of the library:

  • Reuse message objects when possible. Messages try to keep around any memory they allocate for reuse, even when they are cleared. Thus, if you are handling many messages with the same type and similar structure in succession, it is a good idea to reuse the same message object each time to take load off the memory allocator. However, objects can become bloated over time, especially if your messages vary in “shape” or if you occasionally construct a message that is much larger than usual. You should monitor the sizes of your message objects by calling the SpaceUsed method and delete them once they get too big.
  • Your system’s memory allocator may not be well-optimized for allocating lots of small objects from multiple threads. Try using Google’s TCMalloc instead.

Advanced Usage

Protocol buffers have uses that go beyond simple accessors and serialization. Be sure to explore the C++ API reference to see what else you can do with them.

One key feature provided by protocol message classes is reflection. You can iterate over the fields of a message and manipulate their values without writing your code against any specific message type. One very useful way to use reflection is for converting protocol messages to and from other encodings, such as XML or JSON. A more advanced use of reflection might be to find differences between two messages of the same type, or to develop a sort of “regular expressions for protocol messages” in which you can write expressions that match certain message contents. If you use your imagination, it’s possible to apply Protocol Buffers to a much wider range of problems than you might initially expect!

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *