New feature: proper object lifecycle protocol; init and teardown fragments.

[sod] / lib / sod-hosted.c

diff --git a/lib/sod-hosted.c b/lib/sod-hosted.c
new file mode 100644 (file)
index 0000000..961aa22
--- /dev/null
+++ b/lib/sod-hosted.c
@@ -0,0 +1,105 @@
+/* -*-c-*-
+ *
+ * Runtime support for SOD requiring hosted implementation
+ *
+ * (c) 2015 Straylight/Edgeware
+ */
+
+/*----- Licensing notice --------------------------------------------------*
+ *
+ * This file is part of the Sensible Object Design, an object system for C.
+ *
+ * SOD is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Library General Public License as
+ * published by the Free Software Foundation; either version 2 of the
+ * License, or (at your option) any later version.
+ *
+ * SOD is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with SOD; if not, write to the Free
+ * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
+ * MA 02111-1307, USA.
+ */
+
+/*----- Header files ------------------------------------------------------*/
+
+#include <stdlib.h>
+
+#include "sod.h"
+
+/*----- Main code ---------------------------------------------------------*/
+
+/* --- @sod_make@, @sod_makev@ --- *
+ *
+ * Arguments:  @const SodClass *cls@ = class object for new instance
+ *             @va_list ap, ...@ = initialization keyword arguments
+ *
+ * Returns:    Pointer to the newly-allocated initialized instance, or null.
+ *
+ * Use:                Allocates storage for a new instance, initializes it, and
+ *             returns a pointer to it.  If allocation fails, a null pointer
+ *             is returned instead.
+ *
+ *             This function will allocate the storage using @malloc@, and
+ *             then initialize it as for @sod_init@.
+ *
+ *             It's usually convenient to use the macro @SOD_MAKE@ rather
+ *             than calling @sod_make@ directly.
+ *
+ *             (This function is not available in freestanding environments
+ *             lacking @malloc@ and @free@.)
+ */
+
+void *sod_make(const SodClass *cls, ...)
+{
+  void *p;
+  va_list ap;
+
+  va_start(ap, cls);
+  p = sod_makev(cls, ap);
+  va_end(ap);
+  return (p);
+}
+
+void *sod_makev(const SodClass *cls, va_list ap)
+{
+  void *p;
+
+  if ((p = malloc(cls->cls.initsz)) == 0) return (0);
+  return (sod_initv(cls, p, ap));
+}
+
+/* --- @sod_destroy@ --- *
+ *
+ * Arguments:  @void *p@ = pointer to an instance to be torn down, or null
+ *
+ * Returns:    Zero if the object was freed; nonzero if it refused for some
+ *             reason.
+ *
+ * Use:                Invokes the instance's `teardown' method to release any held
+ *             resources, and then calls @free@ to release the instance's
+ *             storage.  See @sod_teardown@ for details, especially
+ *             regarding the return value's meaning.
+ *
+ *             If @p@ is null, then this function does nothing except
+ *             returns zero.
+ *
+ *             (This function is not available in freestanding environments
+ *             lacking @malloc@ and @free@.)
+ */
+
+int sod_destroy(void *p)
+{
+  int rc;
+
+  if (!p) return (0);
+  rc = sod_teardown(p);
+  if (!rc) free(p);
+  return (rc);
+}
+
+/*----- That's all, folks -------------------------------------------------*/