doc proto-util

Signed-off-by: Mattias Andrée <maandree@operamail.com>

1 files changed, 323 insertions, 0 deletions

diff --git a/doc/info/mds.texinfo b/doc/info/mds.texinfo
index 18a85b1..a090f7b 100644
--- a/doc/info/mds.texinfo
+++ b/doc/info/mds.texinfo
@@ -8703,6 +8703,329 @@ macros, but function-like macros and lvalue-macros use
 shorter. Inclusion-guards are formatted
 @code{MDS_LIBMDSCLIENT_*_H}.
 
+@menu
+* Protocol Utilties::                         Low-level functions for implementing protocols.
+@end menu
+
+
+
+@node Protocol Utilties
+@section Protocol Utilties
+
+@cpindex Implementing protocols
+@cpindex Protocols, implementing
+The header file @file{<libmdsclient/proto-util.h>}
+provides functions that can be used in implementing
+protocols. Using these functions will make it easy
+to implement the protocol, the implementing may
+however be more efficient if you implement everything
+by hand. In particular, protocols that are expected
+to be used very often with similar data may be faster
+if implemented using caching techniques.
+
+The header file provides a function for retrieving
+header files of interest:
+
+@table @asis
+@item @code{libmds_headers_cherrypick} [(@code{char** restrict headers, size_t header_count, size_t* restrict found, libmds_cherrypick_optimisation_t optimisation, ...}) @arrow{} @code{int}]
+@fnindex @code{libmds_headers_cherrypick}
+@cpindex Headers, cherrypicking
+@cpindex Cherrypicking headers
+@cpindex Headers, reading
+@cpindex Reading headers
+This function takes an list of headers as input. The
+headers are provided by the parameter @code{headers},
+and the number of headers is specified by the parameter
+@code{header_count}. These headers must include both
+the names and values. For example:
+@example
+headers = (char[][]) @{
+  "Client ID: 0:1",
+  "Message ID: 12",
+  @};
+@end example
+
+The function will store the number headers it found
+to @code{*found}, unless @code{found} is @code{NULL}.
+Only requested headers are counted.
+
+The function can use optimisations based on the input
+The parameter @code{optimisation} is used to provide
+hints required for optimal optimisation.
+
+@tpindex @code{libmds_cherrypick_optimisation_t}
+@tpindex @code{enum libmds_cherrypick_optimisation}
+@code{optimisation} is defined with the type
+@code{libmds_cherrypick_optimisation_t} @{also known as
+@code{enum libmds_cherrypick_optimisation}@}. Values of
+@code{optimisation} should combine, using bit-wise OR,
+two values defined in @code{libmds_cherrypick_optimisation_t}.
+One of the values should be from the header input
+optimisation group:
+
+@table @code
+@item DO_NOT_SORT = 0
+@code{headers} is neither sorted nor may it its
+elements be reordered. However, the function may
+choose to create a copy of @code{headers} and
+sort that copy, if it sees it as beneficial.
+@item SORT
+@code{headers} is not sorted, but the function
+may sort it without copying it, if it sees it as
+beneficial.
+@item SORTED
+@code{headers} is already sorted in ascending
+order. This means that the function will not
+reorder its elements.
+@end table
+
+The other value should be from the header request
+optimisation group:
+
+@table @code
+@item ARGS_UNSORTED = 0
+The header request list is not sorted.
+@item ARGS_SORTED
+The header request list is sorted in ascending order.
+@end table
+
+Note that @code{DO_NOT_SORT} and @code{ARGS_UNSORTED}
+are both guaranteed to have the value 0. The other
+definitions do not have a guaranteed value, but they
+are guaranteed to be unique and only consist of one
+set bit.
+
+The variadic arguments are used for the header request
+list. The first argument in the variadic argument list
+should be a @code{const char*} that names a requested
+header. It should only contain the name of the header.
+The follow argument should be of the type @code{char**}.
+The first element in this argument will be set the
+the value of the header named by the previous argument,
+or @code{NULL} if not found. This, pair of arguments,
+is repeated once for every requested header. The end
+of the variadic argument list must be marked with a
+@code{NULL}. For example:
+
+@example
+char* recv_client_id;
+char* recv_message_id;
+char* recv_command_id;
+r = libmds_headers_cherrypick(headers, n, NULL, 0,
+  /* Header request starts here */
+  "Client ID", &recv_client_id,
+  "Message ID", &recv_message_id,
+  "Command", &recv_command,
+  NULL);
+@end example
+
+The functions behaviour is undefined for if a header
+is requested more than once, or in an order contrary
+to the specifications provided by @code{optimisation}.
+The functions behaviour is also undefined if the input
+headers are in an order contrary to the specifications
+provided by @code{optimisation}.
+
+Upon successful completion, even if no requested headers
+are found, this function returned zero. On error, @code{-1}
+is returned and @code{errno} is set to indicate the error.
+
+This function can fail with errno set to @code{ENOMEM},
+if the process cannot allocate required memory.
+
+The call must not free returned header values. They are
+freed automatically when corresponding element in the
+header input list is freed. The input headers are returned
+with an offset. This also means that the returned values
+will be modified if the value part of the input headers are
+modified.
+@end table
+
+The header file also provides four pre-optimised version
+of @code{libmds_headers_cherrypick}. These functionf behaves
+like @code{libmds_headers_cherrypick}, except they does not
+have the optimisation parameter, and return the number of
+found headers rather than storing it using a pointer.
+Additionally these function cannot fail.
+
+@table @asis
+@item @code{libmds_headers_cherrypick_linear_unsorted} [(@code{char** restrict headers, size_t header_count, ...}) @arrow{} @code{size_t}]
+@fnindex @code{libmds_headers_cherrypick_linear_unsorted}
+This function is not optimised. Because of its low overhead
+it can still be the fastest choice.
+@item @code{libmds_headers_cherrypick_linear_sorted} [(@code{char** restrict headers, size_t header_count, ...}) @arrow{} @code{size_t}]
+@fnindex @code{libmds_headers_cherrypick_linear_sorted}
+This function uses linear search, but uses an optimised based
+on the assumption that both the input header list and the
+header request list are sorted in ascending order. Because of
+its low overhead it can still be faster than
+@code{libmds_headers_cherrypick_binary_sorted}.
+@item @code{libmds_headers_cherrypick_binary_unsorted} [(@code{char** restrict headers, size_t header_count, ...}) @arrow{} @code{size_t}]
+@fnindex @code{libmds_headers_cherrypick_binary_unsorted}
+This function uses binary search. It assumes that the
+header input list sorted in ascending order, header request
+list is unsorted.
+@item @code{libmds_headers_cherrypick_binary_sorted} [(@code{char** restrict headers, size_t header_count, ...}) @arrow{} @code{size_t}]
+@fnindex @code{libmds_headers_cherrypick_binary_sorted}
+This function uses binary search. It assumes that the
+both the header input list and header request list are
+sorted in ascending order. It seeks for the headers in
+the order the are provided in the header request list,
+and adjusts the lower bound on the binary search each
+time it founds a header.
+@end table
+
+Currently it is assumed that these are the only useful
+optimisations. This may however change in the future,
+and some optimisations may even be removed. Therefore
+the user of the library can check at compile time weather
+the functions are still available. This is done by checking
+that a macro with exactly the same name as the function
+is defined.
+
+@cpindex Sorting headers
+@cpindex Headers, sorting
+If you want to sort a list of headers. You need to be
+aware that the header should treated as ending at the
+first occurrence of a colon followed by a blank space.
+Because of this, @file{<libmdsclient/proto-util.h>}
+provides a function for sorting a list of headers.
+
+@table @asis
+@item @code{libmds_headers_sort} [(@code{char** restrict headers, size_t header_count}) @arrow{} @code{void}]
+@fnindex @code{libmds_headers_sort}
+This function takes the list of headers in the parameter
+@code{headers} and the number of headers in the parameter
+@code{header_count}. It cannot fail, and thus does not
+return a value.
+
+This function sorts the headers in ascending order,
+and is used internally by @code{libmds_headers_cherrypick}
+if it chooses to sort headers.
+@end table
+
+@file{<libmdsclient/proto-util.h>} also provides a function
+for composing messages:
+
+@table @asis
+@item @code{libmds_compose} [(@code{char** restrict buffer, size_t* restrict buffer_size, size_t* restrict length, const char* restrict payload, const size_t* restrict payload_length, ...}) @arrow{} @code{int}]
+@fnindex @code{libmds_compose}
+@cpindex Messages, composing
+@cpindex Composing messages
+@cpindex Messages, writting
+@cpindex Writting messages
+This function provides a simple way for writting message
+that can be send to the display server. The function writes
+the message on a buffer provides by the caller. This buffer
+is reallocationed by the function if necessary.
+
+The buffer is provided by a pointer, @code{buffer} to the
+buffer. @code{*buffer} is changed to the new buffer pointer
+if it is reallocated. The current size of @code{*buffer}
+should be stored @code{*buffer_size}. @code{*buffer_size}
+will be updated with the new allocation size if the buffer
+is reallocated. Neither if these pointers may be @code{NULL}.
+However, @code{*buffer} should be @code{NULL} if
+@code{*buffer_size} is zero, and vice versa.
+
+The length of the written message will be saved to
+@code{length}. @code{length} must not be @code{NULL}.
+
+If the message should include a payload. It should be
+provided using the parameter @code{payload}. If the message
+should not have a payload @code{payload} should be @code{NULL}.
+The argument @code{payload_length} should point to a value
+with the length of the message, or be @code{NULL} if the
+function should measure the @code{payload} by searching for
+a NUL bytes which must exists in such a cass. If
+@code{payload_length} is not @code{NULL}, there is not
+requirement for a NUL byte. If @code{payload} is @code{NULL},
+@code{payload_length} is unused and may have any value.
+
+The function uses variadic arguments for header input.
+The first argument in the variadic argument list should
+be an @code{printf}-formatted format-string that describes
+a header line (header name, colon, blank space, header value.)
+The following arguments are the formatting-arguments for that
+format string. At the end of the list of formatting-arguments,
+this is begin anew for the next header, and so on. After the
+last header, a @code{NULL} should be used to mark the end of
+the list. The header formatting string, may include any
+extensions provided by your C library. Nut is has one additional
+extension: if the formatting-string begins with a question mark,
+the first formatting-argument is if type @code{int} and the
+header is only included if that argument is non-zero.
+This is no way to escape a question mark at the beginning of
+the formatting-string, because headers should never begin
+with a question mark.
+
+Upon successful completion, this function returns zero.
+On error, this function returns @code{-1} and sets @code{errno}
+to indicate the error.
+
+This function may fail with @code{errno} set to @code{ENOMEM}
+if the process cannot allocate more memory.
+
+The functions behaviour is undefined if a header is longer than
+@iftex
+2@sup{15}
+@end iftex
+@ifnottex
+2 to the power of 15
+@end ifnottex
+bytes.
+
+This function shall not be used if there must be a guarantee
+that the written data can be securely erased.
+@end table
+
+The header file also provides a function for finding the
+next unused message ID:
+
+@table @asis
+@item @code{libmds_next_message_id} [(@code{uint32_t* restrict message_id, int (*test)(uint32_t message_id, void* data), void* data}) @arrow{} @code{int}]
+The parameter @code{message_id} is a pointer to the message
+ID counter. It should contain the ID of the previous
+message,@footnote{For the first message, it is preferred
+that this value is @code{UINT32_MAX}, so the first message
+is the ID 0, but it is not a requirement, it should however
+be initialised.} it will be updated with the message ID
+for the new message upon successful completion.
+@code{message_id} must not be @code{NULL}.
+
+The parameter @code{test} can either point to a function
+that is used to test if a message ID is unused, or be
+@code{NULL} if no testing should be done. @code{*test}
+tests whether the message ID provided as the first
+argument is free to be used. The second argument in
+@code{*test} will be the value of the parameter @code{data}
+in the call to the function @code{libmds_next_message_id}.
+@code{data} can e used to deal with threading or any other issues.
+@code{data} may be @code{NULL}. @code{data} is unused if
+@code{test} is @code{NULL}.
+
+Upon successful completion zero is returned. On error
+@code{-1} is returned and @code{errno} is set the indicate
+the error.
+
+This function can fail with errno set to any error thrown
+by @code{*test}, as well as @code{EAGAIN}. @code{EAGAIN}
+is thrown if the function cannot find any free message ID
+to use. It is advisable to make @code{*test} throw this
+immediately if there are no free message ID:s.
+The function cannot fail if @code{test} is @code{NULL}.
+@end table
+
+@fnindex @code{libmds_headers_cherrypick_v}
+@fnindex @code{libmds_headers_cherrypick_linear_unsorted_v}
+@fnindex @code{libmds_headers_cherrypick_linear_sorted_v}
+@fnindex @code{libmds_headers_cherrypick_binary_unsorted_v}
+@fnindex @code{libmds_headers_cherrypick_binary_sorted_v}
+@fnindex @code{libmds_compose_v}
+All functions that uses variadic arguments, have a variant
+that uses @code{va_list} instead. These functions are suffixed
+@code{_v}.
+
 
 
 @node libmdslltk