MODULE: Double-linked lists of unmanaged structs

[Monsieur OUXX]

Hi all,

Here is a module that allows you to store an array of unmanaged structs (which can themselves contain pretty much anything, for example Managed object types like the built-in type 'File').

Current version:
1.0

Targeted version of AGS
Natively made with AGS 3.x, but can be ported very easily to 2.72 if you re-create the console's ListBox in 2.72.

Download location :
http://sourceforge.net/projects/agsh/files/

Intended audience:
There are several other modules that allow you to store 'arrays' of objects or variables. For example, you might consider the "Stack" module by Monkey_05_06.

However, the purpose of the present module is completely different. See "Pros and Cons" below.

How to use it?
     - Download the file
     - Open the project. You can run it to see what it does.
     - The file "kernel.txt" contains the same output as the console.
     - Export all scripts and GUIs
     - Re-import the GUI(s)
     - Re-import the scripts and make sure that they're displayed in the same order in your project (it heavily relies on ordered dependencies)
     - If you intend to use the console :
          . Make sure you call AGSH_Console.BindGUI in the 'ongamestart' function
          . Make sure you call AGSH_Console.OnKeyPress in the 'onkeypress' function
          . Make sure you call AGSH_Console.RepeatedlyExecute in the 'repeatedlyexecute' function
     - Run AGSH_AGS_UnmanagedDLL.Reset_WithDependencies in the 'ongamestart' function

<Edit>Extended capabilities
The default mode of initialization if the module makes it maintain 2 lists : a list of free elements (to allocate) and a list of used elements (that will go back to the previous list once you disallocate them).
However you can create as many lists as you need. to see how to proceed, see the "New" and "Free" functions in the module.


Fully-featured example:
- See the "FileManager" module I'll post in another thread.


Pros and cons:
  About the Stack module:
     - The Stack module converts pretty much anything to Strings (provided it actually can be converted)
     - the parameters of the Stack module work "By copy" (you have to pass the string in paramater and return it - it's copied every time)
     - the allocation and disallocation in memory is dynamic (no space wasted)

  About this module:
     - the code is meant to be duplicated in any module that'd be requiring such storage structure. It's not very elegant but it's a choice (see "Programming style of the module")
     - you can manage the items stored in the structure by using a system of indices, which allows to pass them to functions as 'in/out parameters'. It's very light (note that it's still quite error-prone if you enable the debug).
     - it uses the native types of AGS (no conversion to "String") for a better performance, it it's a critical factor
     - the allocation and disallocation time is constant. It means that whatever the size of your lists, it always takes the same time to find a free slot, and to give it back. (However the complexity for the evaluation of the list is linear; this can be easily workaround'ed by implementing a little counter).
     -  the lists are allocated statically; it means they already use some memory at startup, even if you don't use them. That's a choice.


Note for programers: Programming style of the module
     - It's meant to be duplicated in other modules. But it would be wise to create only one such module for each type of data you'd like to store. For example you could create one for Files, one for GUIs, one for Characters, etc. See "Advanced Example"
     - It's quite heavy (you'll see it embeds many separate scripts). It's by design, for maintainability (it'll be part of a much bigger project).
     - It adopts AGS' object syntax (struct+methods), but all the methods are static. It's to be consistent with the integer indices system, and also because the very nature of this module does that it should match the "Singleton" design pattern.
     - the functions AGSH_Console.OnKeyPress and AGSH_Console.RepeatedlyExecute are called explicitely from the corresponding functions of the global script; I don't use the default functions inside the module. It's by choice. You may disable the integrated console anyway.

[Monsieur OUXX]

<Reserving this post for the possible future edits.>