Lely core libraries  2.2.5
buf.h File Reference

This header file is part of the CAN library; it contains the CAN frame buffer declarations. More...

#include <lely/libc/stdatomic.h>
#include <lely/can/msg.h>
Include dependency graph for buf.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  can_buf
 A CAN frame buffer. More...
 

Macros

#define CAN_BUF_INIT
 The static initializer for struct can_buf.
 

Functions

int can_buf_init (struct can_buf *buf, size_t size)
 Initializes a CAN frame buffer. More...
 
void can_buf_fini (struct can_buf *buf)
 Finalizes a CAN frame buffer. More...
 
struct can_bufcan_buf_create (size_t size)
 Allocates and initializes a CAN frame buffer. More...
 
void can_buf_clear (struct can_buf *buf)
 Clears a CAN frame buffer.
 
size_t can_buf_size (const struct can_buf *buf)
 Returns the number of frames available for reading in a CAN buffer. More...
 
size_t can_buf_capacity (const struct can_buf *buf)
 Returns the number of frames available for writing in a CAN buffer. More...
 
size_t can_buf_reserve (struct can_buf *buf, size_t n)
 Resizes a CAN frame buffer, if necessary, to make room for at least n additional frames. More...
 
size_t can_buf_peek (struct can_buf *buf, struct can_msg *ptr, size_t n)
 Reads, but does not remove, frames from a CAN frame buffer. More...
 
size_t can_buf_read (struct can_buf *buf, struct can_msg *ptr, size_t n)
 Reads, and removes, frames from a CAN frame buffer. More...
 
size_t can_buf_write (struct can_buf *buf, const struct can_msg *ptr, size_t n)
 Writes frames to a CAN frame buffer. More...
 

Detailed Description

This header file is part of the CAN library; it contains the CAN frame buffer declarations.

The CAN frame buffer is implemented as a circular buffer. Apart from can_buf_clear() and can_buf_reserve() (an obviously can_buf_init() and can_buf_fini()), all buffer functions are thread-safe and lock-free, provided there are at most two threads accessing the buffer at the same time (single-reader single-writer).

Author
J. S. Seldenthuis jseld.nosp@m.enth.nosp@m.uis@l.nosp@m.ely..nosp@m.com

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Definition in file buf.h.

Function Documentation

◆ can_buf_init()

int can_buf_init ( struct can_buf buf,
size_t  size 
)

Initializes a CAN frame buffer.

Parameters
bufa pointer to a CAN frame buffer.
sizethe initial size (in number of frames). The size will be rounded up to the nearest power of two minus one.
Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().
See also
can_buf_fini()

Definition at line 39 of file buf.c.

◆ can_buf_fini()

void can_buf_fini ( struct can_buf buf)

Finalizes a CAN frame buffer.

See also
can_buf_init()

Definition at line 67 of file buf.c.

◆ can_buf_create()

struct can_buf* can_buf_create ( size_t  size)

Allocates and initializes a CAN frame buffer.

Parameters
sizethe initial size (in number of frames). The size will be rounded up to the nearest power of two minus one.
Returns
a pointer to a new frame buffer, or NULL on error. In the latter case, the error number can be obtained with get_errc().
See also
can_buf_destroy(), can_buf_init()

Definition at line 75 of file buf.c.

◆ can_buf_size()

size_t can_buf_size ( const struct can_buf buf)
inline

Returns the number of frames available for reading in a CAN buffer.

See also
can_buf_capacity()

Definition at line 210 of file buf.h.

◆ can_buf_capacity()

size_t can_buf_capacity ( const struct can_buf buf)
inline

Returns the number of frames available for writing in a CAN buffer.

See also
can_buf_size()

Definition at line 226 of file buf.h.

◆ can_buf_reserve()

size_t can_buf_reserve ( struct can_buf buf,
size_t  n 
)

Resizes a CAN frame buffer, if necessary, to make room for at least n additional frames.

Note that the new capacity can be larger than the requested capacity.

Returns
the new capacity of the buffer (in number of frames), or 0 on error. In the latter case, the error number can be obtained with get_errc().

Definition at line 111 of file buf.c.

◆ can_buf_peek()

size_t can_buf_peek ( struct can_buf buf,
struct can_msg ptr,
size_t  n 
)
inline

Reads, but does not remove, frames from a CAN frame buffer.

Parameters
bufa pointer to a CAN frame buffer.
ptrthe address at which to store the frames (can be NULL).
nthe number of frames to read.
Returns
the number of frames read.
See also
can_buf_read(), can_buf_write()

Definition at line 242 of file buf.h.

◆ can_buf_read()

size_t can_buf_read ( struct can_buf buf,
struct can_msg ptr,
size_t  n 
)
inline

Reads, and removes, frames from a CAN frame buffer.

Parameters
bufa pointer to a CAN frame buffer.
ptrthe address at which to store the frames (can be NULL).
nthe number of frames to read.
Returns
the number of frames read.
See also
can_buf_peek(), can_buf_write()

Definition at line 268 of file buf.h.

◆ can_buf_write()

size_t can_buf_write ( struct can_buf buf,
const struct can_msg ptr,
size_t  n 
)
inline

Writes frames to a CAN frame buffer.

Parameters
bufa pointer to a CAN frame buffer.
ptrthe address from which to load the frames.
nthe number of frames to write.
Returns
the number of frames written.
See also
can_buf_peek(), can_buf_read()

Definition at line 300 of file buf.h.