Difference between pages "r6:Function:stack query" and "r6:Introduction"

From liblfds.org
(Difference between pages)
Jump to navigation Jump to search
m (1 revision imported)
 
m (1 revision imported)
 
Line 1: Line 1:
==Source Files==
==Data Structures==
/src/stack/stack_query.c
This release of liblfds provides the following;
/inc/liblfds.h


==Enums==
* [[r6:API:Freelist|Freelist]]
enum stack_query_type
* [[r6:API:Queue|Queue]]
{
* [[r6:API:Ringbuffer|Ringbuffer]]
  STACK_QUERY_ELEMENT_COUNT
* [[r6:API:SList|SList]] (logical delete only)
};
* [[r6:API:Stack|Stack]]
 
==Supported Platforms==
This release of liblfds has been ported to the following platforms;
 
{| cellpadding="4" border="1" style="border-collapse:collapse;"
|-
|<STRONG>Operating System</STRONG>
|<STRONG>CPU</STRONG>
|<STRONG>Toolchain</STRONG>
|- valign="top"
|Windows 64-bit
|x64
|1. Microsoft Visual Studio 2008<BR>2. Microsoft Windows SDK and GNUmake >= 3.8.1
|- valign="top"
|Windows 32-bit
|x64<BR>x86
|1. Microsoft Visual Studio 2008<BR>2. Visual C++ 2008 Express Edition<BR>3. Microsoft Windows SDK and GNUmake >= 3.8.1
|- valign="top"
|Windows Kernel
|x64<BR>x86
|1. Windows Driver Kit >= 7.0.0
|- valign="top"
|Linux 64-bit
|x64
|1. GCC >= 4.1.0 and GNUmake >= 3.8.1
|- valign="top"
|Linux 32-bit
|x64<BR>x86<BR>ARM
|1. GCC >= 4.1.0 and GNUmake >= 3.8.1
|-
|}
 
==Tested Platforms==
This release of liblfds has actually been built and where possible tested on the following platforms;
 
{| cellpadding="4" border="1" style="border-collapse:collapse;"
|-
|<STRONG>Hardware</STRONG>
|<STRONG>Operating System</STRONG>
|<STRONG>Toolchain</STRONG>
|<STRONG>Targets</STRONG>
|- valign="top"
|Intel Core i5
|Windows 7 build 7600 64-bit
|Microsoft SDK (unknown verson) and GNUmake 3.8.1
|native
|- valign="top"
|Intel Core i5
|Windows 7 build 7600 64-bit
|Microsoft Windows Driver Kit v7.0.0
|Windows 7 free build 64-bit<BR>Windows 7 free build 32-bit<BR>Windows XP free build 32-bit
|- valign="top"
|VM 64-bit
|Windows 7 build 7600 64-bit
|Visual C++ 2008 Express Edition
|x86
|- valign="top"
|VM 64-bit
|Windows 7 build 7600 64-bit
|Visual C++ 2008 Trial Edition
|x64<BR>x86
|- valign="top"
|x64
|Linux (unknown version, 64-bit)
|GCC (unknown vesion) and GNUmake 3.8.1
|native
|- valign="top"
|VM 64-bit
|Linux (unknown version, 64-bit)
|GCC (unknown vesion) and GNUmake 3.8.1
|native
|- valign="top"
|VM 32-bit
|Linux (unknown version, 32-bit)
|GCC (unknown vesion) and GNUmake 3.8.1
|native
|- valign="top"
|Cortex A9
|Linux (unknown version)
|GCC (unknown version) and GNUmake 3.8.1
|native
|-
|}
 
Versions and platforms have not been rigourously recorded over the last three years so this table is not wholly precise.
 
==Building==
On Windows (user-mode), depending on your target platform, one of the following toolchains is required;
 
* [http://www.microsoft.com/visualstudio/en-gb/default.mspx Microsoft Visual Studio 2008] (expensive)
* [http://www.microsoft.com/express/vc/ Visual C++ 2008 Express Edition] (free, but no 64 bit support)
* [http://msdn.microsoft.com/en-gb/windowsserver/bb980924.aspx Microsoft Windows SDK] (free, no GUI, has 64 bit support) and [http://gnuwin32.sourceforge.net/packages/make.htm GNUmake 3.81]
 
On Windows (kernel-mode), the following toolchain is required;
 
* [http://www.microsoft.com/whdc/devtools/WDK/default.mspx Windows Driver Kit] 7.0.0 or later


==Prototype==
On Linux, the following toolchain is required;
void stack_query( struct stack_state *ss, enum stack_query_type query_type, void *query_input, void *query_output );


==Parameters==
* gcc 4.1.0 or later and GNUmake 3.81
''struct stack_state *ss''
: A stack state as allocated by ''[[r6:Function:stack_new|stack_new]]''.


''enum stack_query_type query_type''
For documentation, see the [[r6:Building Guide|building guide]].
: Indicates which query to perform.


''void *query_input''
==Using==
: A pointer to data, or data cast to a void pointer, which is input data required by requested query. Only some queries require input data.  If no input data is required, set query_input to NULL.
Once built, there is a single header file, ''/inc/liblfds.h'' and a single library file ''/bin/liblfds.*''.  The suffix of the library file varies by platform and by the type of library you have chosen to build (static or dynamic).


''void *query_output''
==Testing and Benchmarking==
: The address of a variable into which the requested information is placed.  The type of variable varies on the type of query; see Notes.
The library comes with a command line test and benchmark program.  This program requires threads.  As such, it is only suitable for platforms providing thread support and which can execute a command line binary.  Currently this means the test and benchmark program works for all platforms except the Windows Kernel.


==Return Value==
For documentation, see the [[r6:Testing and Benchmarking Guide|testing and benchmarking guide]].
No return value.  The variable pointed to by ''query_result'' (the type of which will vary depending on the query, see Notes) will be set; this is the mechanism by which information is passed back to the caller.  Currently, no query can fail, so there is no notion of an error value.


==Notes==
==Porting==
The following query is currently supported;
Both the test program and liblfds provide an abstraction layer which acts to mask platform differences.  Porting is the act of implementing on your platform the functions which make up the abstraction layers.  You do not need to port the test program to port liblfds, but obviously it is recommended, so you can test your port.


* STACK_QUERY_ELEMENT_COUNT
To support liblfds, your platform must support either contigious double-word compare-and-swap (e.g. x86/x64) or contigious double-word load-link/conditional-store where normal loads cannot occur inside the LL/CS pair (e.g. ARM) or single word load-link/conditional-store where normal loads can occur inside the LL/CS pair.
** ''query_input'' is NULL.
** ''query_output'' must point to an ''atom_t'' and this variable is set to hold the total count of elements belonging to the stack's freelist (not the free count, the total count).  It is an approximate value, since the count cannot be atomically updated as elements are added to the freelist. However, the count is incremented immediately after an element is added, so the value will in general be correct or very nearly correct and can at most be inaccurate by the number of threads concurrently adding new elements to the stack (which occurs by calling ''[[r6:Function:stack_guaranteed_push|stack_guaranteed_push]]'').


==See Also==
This requirement excludes the IA64, MIPS, PowerPC and SPARC platforms.
* [[r6:API:Stack|Stack]]
 
For documentation, see the [[r6:Porting Guide|porting guide]].

Latest revision as of 14:07, 4 January 2015

Data Structures

This release of liblfds provides the following;

Supported Platforms

This release of liblfds has been ported to the following platforms;

Operating System CPU Toolchain
Windows 64-bit x64 1. Microsoft Visual Studio 2008
2. Microsoft Windows SDK and GNUmake >= 3.8.1
Windows 32-bit x64
x86 		1. Microsoft Visual Studio 2008
2. Visual C++ 2008 Express Edition
3. Microsoft Windows SDK and GNUmake >= 3.8.1
Windows Kernel x64
x86 		1. Windows Driver Kit >= 7.0.0
Linux 64-bit x64 1. GCC >= 4.1.0 and GNUmake >= 3.8.1
Linux 32-bit x64
x86
ARM 		1. GCC >= 4.1.0 and GNUmake >= 3.8.1

Tested Platforms

This release of liblfds has actually been built and where possible tested on the following platforms;

Hardware Operating System Toolchain Targets
Intel Core i5 Windows 7 build 7600 64-bit Microsoft SDK (unknown verson) and GNUmake 3.8.1 native
Intel Core i5 Windows 7 build 7600 64-bit Microsoft Windows Driver Kit v7.0.0 Windows 7 free build 64-bit
Windows 7 free build 32-bit
Windows XP free build 32-bit
VM 64-bit Windows 7 build 7600 64-bit Visual C++ 2008 Express Edition x86
VM 64-bit Windows 7 build 7600 64-bit Visual C++ 2008 Trial Edition x64
x86
x64 Linux (unknown version, 64-bit) GCC (unknown vesion) and GNUmake 3.8.1 native
VM 64-bit Linux (unknown version, 64-bit) GCC (unknown vesion) and GNUmake 3.8.1 native
VM 32-bit Linux (unknown version, 32-bit) GCC (unknown vesion) and GNUmake 3.8.1 native
Cortex A9 Linux (unknown version) GCC (unknown version) and GNUmake 3.8.1 native

Versions and platforms have not been rigourously recorded over the last three years so this table is not wholly precise.

Building

On Windows (user-mode), depending on your target platform, one of the following toolchains is required;

On Windows (kernel-mode), the following toolchain is required;

On Linux, the following toolchain is required;

  • gcc 4.1.0 or later and GNUmake 3.81

For documentation, see the building guide.

Using

Once built, there is a single header file, /inc/liblfds.h and a single library file /bin/liblfds.*. The suffix of the library file varies by platform and by the type of library you have chosen to build (static or dynamic).

Testing and Benchmarking

The library comes with a command line test and benchmark program. This program requires threads. As such, it is only suitable for platforms providing thread support and which can execute a command line binary. Currently this means the test and benchmark program works for all platforms except the Windows Kernel.

For documentation, see the testing and benchmarking guide.

Porting

Both the test program and liblfds provide an abstraction layer which acts to mask platform differences. Porting is the act of implementing on your platform the functions which make up the abstraction layers. You do not need to port the test program to port liblfds, but obviously it is recommended, so you can test your port.

To support liblfds, your platform must support either contigious double-word compare-and-swap (e.g. x86/x64) or contigious double-word load-link/conditional-store where normal loads cannot occur inside the LL/CS pair (e.g. ARM) or single word load-link/conditional-store where normal loads can occur inside the LL/CS pair.

This requirement excludes the IA64, MIPS, PowerPC and SPARC platforms.

For documentation, see the porting guide.

Retrieved from ‘https://www.liblfds.org/mediawiki/index.php?title=r6:Function:stack_query&oldid=97’