r6.1.0:Upgrading Guide

From liblfds.org
Jump to navigation Jump to search

Introduction

Release 6.1.0 is a (long-overdue) maintenance release. Almost no new functionality has been added, but all existing bugs have been fixed.

Upgrade Paths

The only supported upgrade path is from release 6.0.0 to release 6.1.0.

User-Visible Changes

liblfds

  • The liblfds abstraction layer now contains abstractions for compiler barriers and processor barriers.
  • The method used to inline has changed; all inlining is now static (affecting LFDS610_INLINE define).
  • lfds610_abstraction_aligned_malloc has been replaced by lfds610_abstraction_malloc and this lfds abstraction layer function requires only malloc, rather than aligned malloc.
  • lfds610_abstraction_aligned_free has been replaced by lfds610_abstraction_free and this lfds abstraction layer function requires only free, rather than aligned free.
  • The liblfds abstraction layer is no longer publicly visible in the library.
  • lfds610_slist_delete_element has been renamed lfds610_slist_logically_delete_element and now returns int, rather than void, where the return value is 1 if the call deleted the element or 0 if the element had already been deleted.
  • lfds610_slist_delete_all_elements has been renamed lfds610_slist_single_threaded_physically_delete_all_elements.
  • All data structure now have a lfds610_[data structure]_use function. After a data structure is instantiated, a thread (except for the instantiating thread) must call the lfds610_[data structure]_use function on that instance before using that instance.
  • The argument passed to lfds610_abstraction_increment now has a volatile type qualifier.
  • The ringbuffer query function is now exported to the shared object.

test

  • Added a test for CAS.
  • Proper SList and Stack tests (rather than merely workloads).
  • The iteration argument now works on non-x64 platforms.
  • The benchmark option now supports the iteration argument.

User-Invisible Changes

liblfds

  • Compiler and processor barriers added.
  • The abstraction layer now inlines correctly (hat-tip to "Codeplug").
  • Valgrind clean (hat-tip to "jd").
  • Register starvation with shared object builds fixed.
  • All hand-written ARM assembly code replaced with GCC intrinsics.
  • All hand-written Intel assembly code (except for contigious double-word compare-and-swap) replaced with GCC intrinsics.

test

  • Thread affinity added to the Linux thread starter function.

Upgrading

Globally search and replace "lfds600" with "lfds610" and "LFDS600" with "LFDS610".

Modify your build system to take into account the changes in header file name, library name and library pathname.

Replace all occurances of lfds610_slist_delete_element with lfds610_slist_logically_delete_element.

Replace all occurances of lfds610_slist_delete_all_elements with lfds610_slist_single_threaded_physically_delete_all_elements.

Ensure all threads before using a data structure instance they did not instantiate call lfds610_[data structure]_use on that instance.

If you are running on a third-party port;

  • that port must now specify compiler and processor barriers.
  • that port must now replace its implementation of lfds610_abstraction_aligned_malloc with lfds610_abstraction_malloc and replace its implementation of lfds610_abstraction_aligned_free with lfds610_abstraction_free.
  • that port may well need to change the value of LFDS610_INLINE, removing any use of "extern", as inlining is now static.