Merge pull request #1983 from mgreter/feature/C-API-mem-allocator

Expose mem allocator on C-API

Author: xzyfer

Makefile.conf

@@ -33,7 +33,6 @@ SOURCES = \
 	sass_values.cpp \
 	sass_context.cpp \
 	sass_functions.cpp \
-	sass_interface.cpp \
 	sass2scss.cpp \
 	source_map.cpp \
 	to_c.cpp \

docs/api-context.md

@@ -88,7 +88,7 @@ char* source_map_file;
 char* source_map_root;
 ```
 ```C
-// Custom functions that can be called from sccs code
+// Custom functions that can be called from Sass code
 Sass_C_Function_List c_functions;
 ```
 ```C
@@ -168,12 +168,12 @@ struct Sass_Compiler* sass_make_data_compiler (struct Sass_Data_Context* data_ct
 
 // Execute the different compilation steps individually
 // Usefull if you only want to query the included files
-int sass_compiler_parse(struct Sass_Compiler* compiler);
-int sass_compiler_execute(struct Sass_Compiler* compiler);
+int sass_compiler_parse (struct Sass_Compiler* compiler);
+int sass_compiler_execute (struct Sass_Compiler* compiler);
 
 // Release all memory allocated with the compiler
 // This does _not_ include any contexts or options
-void sass_delete_compiler(struct Sass_Compiler* compiler);
+void sass_delete_compiler (struct Sass_Compiler* compiler);
 
 // Release all memory allocated and also ourself
 void sass_delete_file_context (struct Sass_File_Context* ctx);

docs/api-doc.md

@@ -16,24 +16,14 @@ This will automatically load all other headers too!
 #include "sass/context.h"
 ```
 
-### Deprecated usage
-
-The old API is kept in the source for backward compatibility.
-It's deprecated and incompatible with this documentation, use `sass/context.h`!
-
-```C
-// deprecated interface
-#include "sass/interface.h"
-```
-
 ## Basic C Example
 
 ```C
 #include <stdio.h>
 #include "sass/context.h"
 
 int main() {
-  puts(libsass_VERSION());
+  puts(libsass_version());
   return 0;
 }
 ```
@@ -114,6 +104,34 @@ This mirrors very well how `libsass` uses these structures.
 
 Structs can be down-casted to access `context` or `options`!
 
+## Memory handling and life-cycles
+
+We keep memory around for as long as the main [context](api-context.md) object is not destroyed (`sass_delete_context`). LibSass will create copies of most inputs/options beside the main sass code.
+You need to allocate and fill that buffer before passing it to LibSass. You may also overtake memory management from libsass for certain return values (i.e. `sass_context_take_output_string`).
+
+```C
+// to allocate buffer to be filled
+void* sass_alloc_memory(size_t size);
+// to allocate a buffer from existing string
+char* sass_copy_c_string(const char* str);
+// to free overtaken memory when done
+void sass_free_memory(void* ptr);
+```
+
+## Miscellaneous API functions
+
+```C
+// Some convenient string helper function
+char* sass_string_unquote (const char* str);
+char* sass_string_quote (const char* str, const char quote_mark);
+
+// Resolve a file via the given include paths in the include char* array
+char* sass_resolve_file (const char* path, const char* incs[]);
+
+// Get compiled libsass version
+const char* libsass_version(void);
+```
+
 ## Common Pitfalls
 
 **input_path**

docs/api-importer-example.md

@@ -10,10 +10,10 @@ Sass_Import_List sass_importer(const char* path, Sass_Importer_Entry cb, struct
   // get the cookie from importer descriptor
   void* cookie = sass_importer_get_cookie(cb);
   Sass_Import_List list = sass_make_import_list(2);
-  const char* local = "local { color: green; }";
-  const char* remote = "remote { color: red; }";
-  list[0] = sass_make_import_entry("/tmp/styles.scss", strdup(local), 0);
-  list[1] = sass_make_import_entry("http://www.example.com", strdup(remote), 0);
+  char* local = sass_copy_c_string("local { color: green; }");
+  char* remote = sass_copy_c_string("remote { color: red; }");
+  list[0] = sass_make_import_entry("/tmp/styles.scss", local, 0);
+  list[1] = sass_make_import_entry("http://www.example.com", remote, 0);
   return list;
 }
 
@@ -84,7 +84,7 @@ Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_
   Sass_Import_List list = sass_make_import_list(1);
   const char* message = "some error message";
   list[0] = sass_make_import_entry(path, 0, 0);
-  sass_import_set_error(list[0], strdup(message), 0, 0);
+  sass_import_set_error(list[0], sass_copy_c_string(message), 0, 0);
   return list;
 }
 

include/sass/base.h

@@ -62,6 +62,13 @@ enum Sass_Output_Style {
   SASS_STYLE_TO_SASS
 };
 
+// to allocate buffer to be filled
+void* sass_alloc_memory(size_t size);
+// to allocate a buffer from existing string
+char* sass_copy_c_string(const char* str);
+// to free overtaken memory when done
+void sass_free_memory(void* ptr);
+
 // Some convenient string helper function
 ADDAPI char* ADDCALL sass_string_quote (const char* str, const char quote_mark);
 ADDAPI char* ADDCALL sass_string_unquote (const char* str);

include/sass/interface.h

@@ -289,7 +289,7 @@ namespace Sass {
     const char* contents = resources[idx].contents;
     // keep a copy of the path around (for parserstates)
     // ToDo: we clean it, but still not very elegant!?
-    strings.push_back(sass_strdup(inc.abs_path.c_str()));
+    strings.push_back(sass_copy_c_string(inc.abs_path.c_str()));
     // create the initial parser state from resource
     ParserState pstate(strings.back(), contents, idx);
 
@@ -519,7 +519,7 @@ namespace Sass {
     }
     // create a copy of the resulting buffer string
     // this must be freed or taken over by implementor
-    return sass_strdup(emitted.buffer.c_str());
+    return sass_copy_c_string(emitted.buffer.c_str());
   }
 
   void Context::apply_custom_headers(Block* root, const char* ctx_path, ParserState pstate)
@@ -606,7 +606,7 @@ namespace Sass {
 
     // ToDo: this may be resolved via custom importers
     std::string abs_path(rel2abs(entry_path));
-    char* abs_path_c_str = sass_strdup(abs_path.c_str());
+    char* abs_path_c_str = sass_copy_c_string(abs_path.c_str());
     strings.push_back(abs_path_c_str);
 
     // create entry only for the import stack
@@ -693,7 +693,7 @@ namespace Sass {
     if (source_map_file == "") return 0;
     char* result = 0;
     std::string map = emitter.render_srcmap(*this);
-    result = sass_strdup(map.c_str());
+    result = sass_copy_c_string(map.c_str());
     return result;
   }
 

src/context.cpp

@@ -197,7 +197,7 @@ namespace Sass {
   {
     Expression* mq = m->media_queries()->perform(&eval);
     std::string str_mq(mq->to_string(ctx.c_options));
-    char* str = sass_strdup(str_mq.c_str());
+    char* str = sass_copy_c_string(str_mq.c_str());
     ctx.strings.push_back(str);
     Parser p(Parser::from_c_str(str, ctx, mq->pstate()));
     mq = p.parse_media_queries();

src/expand.cpp

@@ -11,26 +11,50 @@
 extern "C" {
   using namespace Sass;
 
+  // Allocate libsass heap memory
+  // Don't forget string termination!
+  void* ADDCALL sass_alloc_memory(size_t size)
+  {
+    void* ptr = malloc(size);
+    if (ptr == NULL)
+      out_of_memory();
+    return ptr;
+  }
+
+  char* ADDCALL sass_copy_c_string(const char* str)
+  {
+    size_t len = strlen(str) + 1;
+    char* cpy = (char*) sass_alloc_memory(len);
+    std::memcpy(cpy, str, len);
+    return cpy;
+  }
+
+  // Deallocate libsass heap memory
+  void ADDCALL sass_free_memory(void* ptr)
+  {
+    if (ptr) free (ptr);
+  }
+
   // caller must free the returned memory
   char* ADDCALL sass_string_quote (const char *str, const char quote_mark)
   {
     std::string quoted = quote(str, quote_mark);
-    return sass_strdup(quoted.c_str());
+    return sass_copy_c_string(quoted.c_str());
   }
 
   // caller must free the returned memory
   char* ADDCALL sass_string_unquote (const char *str)
   {
     std::string unquoted = unquote(str);
-    return sass_strdup(unquoted.c_str());
+    return sass_copy_c_string(unquoted.c_str());
   }
 
   // Make sure to free the returned value!
   // Incs array has to be null terminated!
   char* ADDCALL sass_resolve_file (const char* file, const char* paths[])
   {
     std::string resolved(File::find_file(file, paths));
-    return sass_strdup(resolved.c_str());
+    return sass_copy_c_string(resolved.c_str());
   }
 
   // Get compiled libsass version