2018-02-04 03:22:01 +01:00
|
|
|
// Matrix Construct
|
|
|
|
//
|
|
|
|
// Copyright (C) Matrix Construct Developers, Authors & Contributors
|
|
|
|
// Copyright (C) 2016-2018 Jason Volk <jason@zemos.net>
|
|
|
|
//
|
|
|
|
// Permission to use, copy, modify, and/or distribute this software for any
|
|
|
|
// purpose with or without fee is hereby granted, provided that the above
|
|
|
|
// copyright notice and this permission notice is present in all copies. The
|
|
|
|
// full license for this software is available in the LICENSE file.
|
MAPI IV. This iteration leverages the C++11 standardized RTTI.
* Simplifies the export declarations for module developers. While
MAPI III utilized a flexible key-value vector to eliminate positional
arguments in a header initializer, now the developer simply makes
a list of pointers to what they want to export for injection into
IRCd. Example:
mapi::header IRCD_MODULE
{
"mymod",
"My module adds a command, a hook, and a CLICAP",
&my_cmdtab,
&some_hook,
&clicaptab
};
* Distributes the handlers for items passed to the above vector.
Anyone can add a type-handler to the module system from anywhere in IRCd
(and other modules?) When your type is encountered a handler is called
providing the symbol name to read out of the module. Example in parser.cc:
mods::add_loader<Message>([]
(mod &loading, const std::string &symbol)
{
auto &msg(get<Message>(loading, symbol));
add_command(msg.name, msg);
});
2016-08-29 21:09:59 +02:00
|
|
|
|
|
|
|
#pragma once
|
|
|
|
#define HAVE_IRCD_MAPI_H
|
|
|
|
|
2019-05-02 02:06:40 +02:00
|
|
|
#define IRCD_MODULE_HEADER_SYMBOL_NAME "ircd_module"
|
|
|
|
#define IRCD_MODULE_EXPORT_CODE_SECTION "ircd.code"
|
|
|
|
#define IRCD_MODULE_EXPORT_CODE_VISIBILITY "default"
|
|
|
|
#define IRCD_MODULE_EXPORT_DATA_SECTION "ircd.data"
|
|
|
|
#define IRCD_MODULE_EXPORT_DATA_VISIBILITY "default"
|
|
|
|
|
|
|
|
/// Macro of decorations used on function definitions in modules which are
|
2019-05-03 01:23:56 +02:00
|
|
|
/// published for demangling and use by libircd.
|
2019-03-24 21:18:03 +01:00
|
|
|
#define IRCD_MODULE_EXPORT_CODE \
|
2019-05-01 00:14:04 +02:00
|
|
|
__attribute__((section(IRCD_MODULE_EXPORT_CODE_SECTION))) \
|
2019-05-02 02:06:40 +02:00
|
|
|
__attribute__((visibility(IRCD_MODULE_EXPORT_CODE_VISIBILITY)))
|
2019-03-24 21:18:03 +01:00
|
|
|
|
2019-05-02 02:06:40 +02:00
|
|
|
/// Macro of decorations used on object definitions in modules which are
|
2019-05-03 01:23:56 +02:00
|
|
|
/// published for demangling and use by libircd (object equivalent).
|
2019-03-24 21:18:03 +01:00
|
|
|
#define IRCD_MODULE_EXPORT_DATA \
|
2019-05-01 00:14:04 +02:00
|
|
|
__attribute__((section(IRCD_MODULE_EXPORT_DATA_SECTION))) \
|
2019-05-02 02:06:40 +02:00
|
|
|
__attribute__((visibility(IRCD_MODULE_EXPORT_CODE_VISIBILITY))) \
|
|
|
|
__attribute__((externally_visible))
|
|
|
|
|
|
|
|
// Common convenience aliases
|
2019-05-03 01:23:56 +02:00
|
|
|
#define IRCD_MODULE_EXPORT \
|
|
|
|
IRCD_MODULE_EXPORT_CODE
|
2019-03-24 21:18:03 +01:00
|
|
|
|
2019-05-02 02:06:40 +02:00
|
|
|
/// Module declaration
|
|
|
|
#define IRCD_MODULE \
|
|
|
|
__attribute__((visibility("default"))) \
|
|
|
|
__attribute__((externally_visible)) \
|
|
|
|
ircd_module
|
2019-02-09 23:39:17 +01:00
|
|
|
|
2017-09-12 18:37:44 +02:00
|
|
|
/// Module API: Interface for module developers.
|
2017-08-28 23:51:22 +02:00
|
|
|
namespace ircd::mapi
|
|
|
|
{
|
|
|
|
struct header;
|
2018-10-25 22:03:07 +02:00
|
|
|
struct metablock;
|
2019-03-28 08:42:06 +01:00
|
|
|
using magic_t = uint32_t;
|
2019-04-19 01:54:23 +02:00
|
|
|
using version_t = uint16_t;
|
|
|
|
using serial_t = uint16_t;
|
2018-10-25 22:03:07 +02:00
|
|
|
using meta_data = std::map<string_view, string_view, std::less<>>;
|
|
|
|
using init_func = std::function<void ()>;
|
|
|
|
using fini_func = std::function<void ()>;
|
MAPI IV. This iteration leverages the C++11 standardized RTTI.
* Simplifies the export declarations for module developers. While
MAPI III utilized a flexible key-value vector to eliminate positional
arguments in a header initializer, now the developer simply makes
a list of pointers to what they want to export for injection into
IRCd. Example:
mapi::header IRCD_MODULE
{
"mymod",
"My module adds a command, a hook, and a CLICAP",
&my_cmdtab,
&some_hook,
&clicaptab
};
* Distributes the handlers for items passed to the above vector.
Anyone can add a type-handler to the module system from anywhere in IRCd
(and other modules?) When your type is encountered a handler is called
providing the symbol name to read out of the module. Example in parser.cc:
mods::add_loader<Message>([]
(mod &loading, const std::string &symbol)
{
auto &msg(get<Message>(loading, symbol));
add_command(msg.name, msg);
});
2016-08-29 21:09:59 +02:00
|
|
|
|
2018-10-25 22:03:07 +02:00
|
|
|
/// Used to communicate whether a module unload actually took place. dlclose() is allowed to return
|
|
|
|
/// success but the actual static destruction of the module's contents doesn't lie. (mods.cc)
|
|
|
|
extern bool static_destruction;
|
|
|
|
|
|
|
|
/// The name of the header variable in the module must match this string
|
2017-08-28 23:51:22 +02:00
|
|
|
const char *const header_symbol_name
|
|
|
|
{
|
2019-05-02 02:06:40 +02:00
|
|
|
IRCD_MODULE_HEADER_SYMBOL_NAME
|
2017-08-28 23:51:22 +02:00
|
|
|
};
|
2019-02-09 12:05:19 +01:00
|
|
|
|
2019-03-24 21:18:03 +01:00
|
|
|
/// Symbols in these sections are automatically demangle-mapped on load.
|
|
|
|
extern const char *const import_section_names[];
|
2018-10-25 22:03:07 +02:00
|
|
|
}
|
MAPI IV. This iteration leverages the C++11 standardized RTTI.
* Simplifies the export declarations for module developers. While
MAPI III utilized a flexible key-value vector to eliminate positional
arguments in a header initializer, now the developer simply makes
a list of pointers to what they want to export for injection into
IRCd. Example:
mapi::header IRCD_MODULE
{
"mymod",
"My module adds a command, a hook, and a CLICAP",
&my_cmdtab,
&some_hook,
&clicaptab
};
* Distributes the handlers for items passed to the above vector.
Anyone can add a type-handler to the module system from anywhere in IRCd
(and other modules?) When your type is encountered a handler is called
providing the symbol name to read out of the module. Example in parser.cc:
mods::add_loader<Message>([]
(mod &loading, const std::string &symbol)
{
auto &msg(get<Message>(loading, symbol));
add_command(msg.name, msg);
});
2016-08-29 21:09:59 +02:00
|
|
|
|
2018-10-25 22:03:07 +02:00
|
|
|
/// The magic number at the front of the header
|
|
|
|
constexpr const ircd::mapi::magic_t
|
|
|
|
IRCD_MAPI_MAGIC
|
|
|
|
{
|
2019-03-28 08:42:06 +01:00
|
|
|
0x112Cd
|
2018-10-25 22:03:07 +02:00
|
|
|
};
|
2016-11-02 23:12:56 +01:00
|
|
|
|
2018-10-25 22:03:07 +02:00
|
|
|
/// The version number of this module's header.
|
|
|
|
constexpr const ircd::mapi::version_t
|
|
|
|
IRCD_MAPI_VERSION
|
|
|
|
{
|
|
|
|
4
|
|
|
|
};
|
MAPI IV. This iteration leverages the C++11 standardized RTTI.
* Simplifies the export declarations for module developers. While
MAPI III utilized a flexible key-value vector to eliminate positional
arguments in a header initializer, now the developer simply makes
a list of pointers to what they want to export for injection into
IRCd. Example:
mapi::header IRCD_MODULE
{
"mymod",
"My module adds a command, a hook, and a CLICAP",
&my_cmdtab,
&some_hook,
&clicaptab
};
* Distributes the handlers for items passed to the above vector.
Anyone can add a type-handler to the module system from anywhere in IRCd
(and other modules?) When your type is encountered a handler is called
providing the symbol name to read out of the module. Example in parser.cc:
mods::add_loader<Message>([]
(mod &loading, const std::string &symbol)
{
auto &msg(get<Message>(loading, symbol));
add_command(msg.name, msg);
});
2016-08-29 21:09:59 +02:00
|
|
|
|
2019-04-19 01:54:23 +02:00
|
|
|
/// The serial number recorded by the module header. We increment this number
|
|
|
|
/// after removing a module from the project because that module will still
|
|
|
|
/// remain in the user's install directory. The removed module's serial nr
|
|
|
|
/// will not be incremented anymore; libircd can ignore modules with serial
|
|
|
|
/// numbers < this value.
|
|
|
|
constexpr const ircd::mapi::serial_t
|
|
|
|
IRCD_MAPI_SERIAL
|
|
|
|
{
|
|
|
|
1
|
|
|
|
};
|
|
|
|
|
2019-02-10 00:36:51 +01:00
|
|
|
/// Module Header
|
|
|
|
///
|
|
|
|
/// A static instance of this class must be included in an IRCd module with
|
|
|
|
/// the unmangled name of IRCD_MODULE (thus there can be only one). It must
|
|
|
|
/// be externally visible. If this is not present or not visible, ircd::mods
|
|
|
|
/// will not consider the file to be an IRCd module and it will be ignored.
|
|
|
|
///
|
2019-05-02 02:06:40 +02:00
|
|
|
struct ircd::mapi::header
|
2017-03-18 01:45:43 +01:00
|
|
|
{
|
2018-10-25 22:03:07 +02:00
|
|
|
const magic_t magic {IRCD_MAPI_MAGIC}; // The magic must match
|
|
|
|
const version_t version {IRCD_MAPI_VERSION}; // Version indicator
|
2019-04-19 01:54:23 +02:00
|
|
|
const serial_t serial {IRCD_MAPI_SERIAL}; // Serial indicator
|
2018-10-25 22:03:07 +02:00
|
|
|
const int64_t timestamp {RB_DATECODE}; // Module's compile epoch
|
|
|
|
std::unique_ptr<metablock> meta; // Non-standard-layout header data
|
|
|
|
mods::mod *self {nullptr}; // Point to mod instance once loaded
|
2016-09-13 10:29:50 +02:00
|
|
|
|
|
|
|
// get and set metadata
|
2018-10-25 22:03:07 +02:00
|
|
|
const string_view &operator[](const string_view &s) const;
|
|
|
|
string_view &operator[](const string_view &s);
|
MAPI IV. This iteration leverages the C++11 standardized RTTI.
* Simplifies the export declarations for module developers. While
MAPI III utilized a flexible key-value vector to eliminate positional
arguments in a header initializer, now the developer simply makes
a list of pointers to what they want to export for injection into
IRCd. Example:
mapi::header IRCD_MODULE
{
"mymod",
"My module adds a command, a hook, and a CLICAP",
&my_cmdtab,
&some_hook,
&clicaptab
};
* Distributes the handlers for items passed to the above vector.
Anyone can add a type-handler to the module system from anywhere in IRCd
(and other modules?) When your type is encountered a handler is called
providing the symbol name to read out of the module. Example in parser.cc:
mods::add_loader<Message>([]
(mod &loading, const std::string &symbol)
{
auto &msg(get<Message>(loading, symbol));
add_command(msg.name, msg);
});
2016-08-29 21:09:59 +02:00
|
|
|
|
2018-03-24 02:00:21 +01:00
|
|
|
// become self
|
|
|
|
operator const mods::mod &() const;
|
|
|
|
operator mods::mod &();
|
|
|
|
|
2019-04-19 02:15:17 +02:00
|
|
|
header(const string_view &,
|
2018-10-25 22:03:07 +02:00
|
|
|
init_func = {},
|
|
|
|
fini_func = {});
|
2016-09-05 22:06:30 +02:00
|
|
|
|
2018-10-25 22:03:07 +02:00
|
|
|
header(header &&) = delete;
|
|
|
|
header(const header &) = delete;
|
2016-09-13 10:31:12 +02:00
|
|
|
~header() noexcept;
|
MAPI IV. This iteration leverages the C++11 standardized RTTI.
* Simplifies the export declarations for module developers. While
MAPI III utilized a flexible key-value vector to eliminate positional
arguments in a header initializer, now the developer simply makes
a list of pointers to what they want to export for injection into
IRCd. Example:
mapi::header IRCD_MODULE
{
"mymod",
"My module adds a command, a hook, and a CLICAP",
&my_cmdtab,
&some_hook,
&clicaptab
};
* Distributes the handlers for items passed to the above vector.
Anyone can add a type-handler to the module system from anywhere in IRCd
(and other modules?) When your type is encountered a handler is called
providing the symbol name to read out of the module. Example in parser.cc:
mods::add_loader<Message>([]
(mod &loading, const std::string &symbol)
{
auto &msg(get<Message>(loading, symbol));
add_command(msg.name, msg);
});
2016-08-29 21:09:59 +02:00
|
|
|
};
|
|
|
|
|
2018-10-25 22:03:07 +02:00
|
|
|
struct ircd::mapi::metablock
|
|
|
|
{
|
|
|
|
init_func init; // Executed after dlopen()
|
|
|
|
fini_func fini; // Executed before dlclose()
|
|
|
|
meta_data meta; // Various key-value metadata
|
2019-04-19 02:15:17 +02:00
|
|
|
|
|
|
|
metablock(const string_view &, init_func &&, fini_func &&);
|
2018-10-25 22:03:07 +02:00
|
|
|
};
|
|
|
|
|
|
|
|
static_assert
|
|
|
|
(
|
|
|
|
std::is_standard_layout<ircd::mapi::header>(),
|
|
|
|
"The MAPI header must be standard layout so the magic and version numbers"
|
|
|
|
" can be parsed from the shared object file by external applications."
|
|
|
|
);
|
|
|
|
|
|
|
|
static_assert
|
|
|
|
(
|
2019-03-28 08:42:06 +01:00
|
|
|
sizeof(ircd::mapi::header) == 4 + 4 + 8 + 8 + 8,
|
2018-10-25 22:03:07 +02:00
|
|
|
"The MAPI header size has changed on this platform."
|
|
|
|
);
|
2019-04-19 02:15:17 +02:00
|
|
|
|
|
|
|
inline
|
|
|
|
__attribute__((always_inline))
|
|
|
|
ircd::mapi::header::header(const string_view &description,
|
|
|
|
init_func init,
|
|
|
|
fini_func fini)
|
|
|
|
:meta
|
|
|
|
{
|
|
|
|
new metablock
|
|
|
|
{
|
|
|
|
description, std::move(init), std::move(fini)
|
|
|
|
}
|
|
|
|
}
|
|
|
|
{}
|